diff options
Diffstat (limited to 'doc/sphinx')
71 files changed, 41883 insertions, 0 deletions
diff --git a/doc/sphinx/README.rst b/doc/sphinx/README.rst new file mode 100644 index 0000000000..881f7a310d --- /dev/null +++ b/doc/sphinx/README.rst @@ -0,0 +1,539 @@ +============================= + Documenting Coq with Sphinx +============================= + +.. + README.rst is auto-generated from README.template.rst and the coqrst docs; + use ``doc/tools/coqrst/regen_readme.py`` to rebuild it. + +Coq's reference manual is written in `reStructuredText <http://www.sphinx-doc.org/en/master/usage/restructuredtext/basics.html>`_ (“reST”), and compiled with `Sphinx <http://www.sphinx-doc.org/en/master/>`_. + +In addition to standard reST directives (a directive is similar to a LaTeX environment) and roles (a role is similar to a LaTeX command), the ``coqrst`` plugin loaded by the documentation uses a custom *Coq domain* — a set of Coq-specific directives that define *objects* like tactics, commands (vernacs), warnings, etc. —, some custom *directives*, and a few custom *roles*. Finally, this manual uses a small DSL to describe tactic invocations and commands. + +Coq objects +=========== + +Our Coq domain define multiple `objects`_. Each object has a *signature* (think *type signature*), followed by an optional body (a description of that object). The following example defines two objects: a variant of the ``simpl`` tactic, and an error that it may raise:: + + .. tacv:: simpl @pattern at {+ @num} + :name: simpl_at + + This applies ``simpl`` only to the :n:`{+ @num}` occurrences of the subterms + matching :n:`@pattern` in the current goal. + + .. exn:: Too few occurrences + :undocumented: + +Objects are automatically collected into indices, and can be linked to using the role version of the object's directive. For example, you could link to the tactic variant above using ``:tacv:`simpl_at```, and to its exception using ``:exn:`Too few occurrences```. + +Names (link targets) are auto-generated for most simple objects, though they can always be overwritten using a ``:name:`` option, as shown above. + +- Options, errors, warnings have their name set to their signature, with ``...`` replacing all notation bits. For example, the auto-generated name of ``.. exn:: @qualid is not a module`` is ``... is not a module``, and a link to it would take the form ``:exn:`... is not a module```. +- Vernacs (commands) have their name set to the first word of their signature. For example, the auto-generated name of ``Axiom @ident : @term`` is ``Axiom``, and a link to it would take the form ``:cmd:`Axiom```. +- Vernac variants, tactic notations, and tactic variants do not have a default name. + +Most objects should have a body (i.e. a block of indented text following the signature, called “contents” in Sphinx terms). Undocumented objects should have the ``:undocumented:`` flag instead, as shown above. When multiple objects have a single description, they can be grouped into a single object, like this (semicolons can be used to separate the names of the objects; names starting with ``_`` will be omitted from the indexes):: + + .. cmdv:: Lemma @ident {? @binders} : @type + Remark @ident {? @binders} : @type + Fact @ident {? @binders} : @type + Corollary @ident {? @binders} : @type + Proposition @ident {? @binders} : @type + :name: Lemma; Remark; Fact; Corollary; Proposition + + These commands are all synonyms of :n:`Theorem @ident {? @binders } : type`. + +Notations +--------- + +The signatures of most objects can be written using a succinct DSL for Coq notations (think regular expressions written with a Lispy syntax). A typical signature might look like ``Hint Extern @num {? @pattern} => @tactic``, which means that the ``Hint Extern`` command takes a number (``num``), followed by an optional pattern, and a mandatory tactic. The language has the following constructs (the full grammar is in `TacticNotations.g </doc/tools/coqrst/notations/TacticNotations.g>`_): + +``@…`` + A placeholder (``@ident``, ``@num``, ``@tactic``\ …) + +``{? …}`` + an optional block + +``{* …}``, ``{+ …}`` + an optional (``*``) or mandatory (``+``) block that can be repeated, with repetitions separated by spaces + +``{*, …}``, ``{+, …}`` + an optional or mandatory repeatable block, with repetitions separated by commas + +``%|``, ``%{``, … + an escaped character (rendered without the leading ``%``) + +.. + FIXME document the new subscript support + +As an exercise, what do the following patterns mean? + +.. code:: + + pattern {+, @term {? at {+ @num}}} + generalize {+, @term at {+ @num} as @ident} + fix @ident @num with {+ (@ident {+ @binder} {? {struct @ident'}} : @type)} + +Objects +------- + +Here is the list of all objects of the Coq domain (The symbol :black_nib: indicates an object whose signature can be written using the notations DSL): + +``.. cmd::`` :black_nib: A Coq command. + Example:: + + .. cmd:: Infix "@symbol" := @term ({+, @modifier}). + + This command is equivalent to :n:`…`. + +``.. cmdv::`` :black_nib: A variant of a Coq command. + Example:: + + .. cmd:: Axiom @ident : @term. + + This command links :token:`term` to the name :token:`term` as its specification in + the global context. The fact asserted by :token:`term` is thus assumed as a + postulate. + + .. cmdv:: Parameter @ident : @term. + + This is equivalent to :n:`Axiom @ident : @term`. + +``.. exn::`` :black_nib: An error raised by a Coq command or tactic. + This commonly appears nested in the ``.. tacn::`` that raises the + exception. + + Example:: + + .. tacv:: assert @form by @tactic + + This tactic applies :n:`@tactic` to solve the subgoals generated by + ``assert``. + + .. exn:: Proof is not complete + + Raised if :n:`@tactic` does not fully solve the goal. + +``.. flag::`` :black_nib: A Coq flag (i.e. a boolean setting). + Example:: + + .. flag:: Nonrecursive Elimination Schemes + + Controls whether types declared with the keywords + :cmd:`Variant` and :cmd:`Record` get an automatic declaration of + induction principles. + +``.. opt::`` :black_nib: A Coq option (a setting with non-boolean value, e.g. a string or numeric value). + Example:: + + .. opt:: Hyps Limit @num + :name Hyps Limit + + Controls the maximum number of hypotheses displayed in goals after + application of a tactic. + +``.. prodn::`` A grammar production. + This is useful if you intend to document individual grammar productions. + Otherwise, use Sphinx's `production lists + <http://www.sphinx-doc.org/en/stable/markup/para.html#directive-productionlist>`_. + + Unlike ``.. productionlist``\ s, this directive accepts notation syntax. + + + Usage:: + + .. prodn:: token += production + .. prodn:: token ::= production + + Example:: + + .. prodn:: term += let: @pattern := @term in @term + .. prodn:: occ_switch ::= { {? + %| - } {* @num } } + +``.. table::`` :black_nib: A Coq table, i.e. a setting that is a set of values. + Example:: + + .. table:: Search Blacklist @string + :name: Search Blacklist + + Controls ... + +``.. tacn::`` :black_nib: A tactic, or a tactic notation. + Example:: + + .. tacn:: do @num @expr + + :token:`expr` is evaluated to ``v`` which must be a tactic value. … + +``.. tacv::`` :black_nib: A variant of a tactic. + Example:: + + .. tacn:: fail + + This is the always-failing tactic: it does not solve any goal. It is + useful for defining other tacticals since it can be caught by + :tacn:`try`, :tacn:`repeat`, :tacn:`match goal`, or the branching + tacticals. … + + .. tacv:: fail @natural + + The number is the failure level. If no level is specified, it + defaults to 0. … + +``.. thm::`` A theorem. + Example:: + + .. thm:: Bound on the ceiling function + + Let :math:`p` be an integer and :math:`c` a rational constant. Then + :math:`p \ge c \rightarrow p \ge \lceil{c}\rceil`. + +``.. warn::`` :black_nib: An warning raised by a Coq command or tactic.. + Do not mistake this for ``.. warning::``; this directive is for warning + messages produced by Coq. + + + Example:: + + .. warn:: Ambiguous path + + When the coercion :token:`qualid` is added to the inheritance graph, non + valid coercion paths are ignored. + +Coq directives +============== + +In addition to the objects above, the ``coqrst`` Sphinx plugin defines the following directives: + +``.. coqtop::`` A reST directive to describe interactions with Coqtop. + Usage:: + + .. coqtop:: options… + + Coq code to send to coqtop + + Example:: + + .. coqtop:: in reset + + Print nat. + Definition a := 1. + + The blank line after the directive is required. If you begin a proof, + use the ``abort`` option to reset coqtop for the next example. + + Here is a list of permissible options: + + - Display options (choose exactly one) + + - ``all``: Display input and output + - ``in``: Display only input + - ``out``: Display only output + - ``none``: Display neither (useful for setup commands) + + - Behavior options + + - ``reset``: Send a ``Reset Initial`` command before running this block + - ``fail``: Don't die if a command fails, implies ``warn`` (so no need to put both) + - ``warn``: Don't die if a command emits a warning + - ``restart``: Send a ``Restart`` command before running this block (only works in proof mode) + - ``abort``: Send an ``Abort All`` command after running this block (leaves all pending proofs if any) + + ``coqtop``\ 's state is preserved across consecutive ``.. coqtop::`` blocks + of the same document (``coqrst`` creates a single ``coqtop`` process per + reST source file). Use the ``reset`` option to reset Coq's state. + +``.. coqdoc::`` A reST directive to display Coqtop-formatted source code. + Usage:: + + .. coqdoc:: + + Coq code to highlight + + Example:: + + .. coqdoc:: + + Definition test := 1. + +``.. example::`` A reST directive for examples. + This behaves like a generic admonition; see + http://docutils.sourceforge.net/docs/ref/rst/directives.html#generic-admonition + for more details. + + Optionally, any text immediately following the ``.. example::`` header is + used as the example's title. + + Example:: + + .. example:: Adding a hint to a database + + The following adds ``plus_comm`` to the ``plu`` database: + + .. coqdoc:: + + Hint Resolve plus_comm : plu. + +``.. inference::`` A reST directive to format inference rules. + This also serves as a small illustration of the way to create new Sphinx + directives. + + Usage:: + + .. inference:: name + + newline-separated premises + -------------------------- + conclusion + + Example:: + + .. inference:: Prod-Pro + + \WTEG{T}{s} + s \in \Sort + \WTE{\Gamma::(x:T)}{U}{\Prop} + ----------------------------- + \WTEG{\forall~x:T,U}{\Prop} + +``.. preamble::`` A reST directive to include a TeX file. + Mostly useful to let MathJax know about `\def`s and `\newcommand`s. The + contents of the TeX file are wrapped in a math environment, as MathJax + doesn't process LaTeX definitions otherwise. + + Usage:: + + .. preamble:: preamble.tex + +Coq roles +========= + +In addition to the objects and directives above, the ``coqrst`` Sphinx plugin defines the following roles: + +``:g:`` Coq code. + Use this for Gallina and Ltac snippets:: + + :g:`apply plus_comm; reflexivity` + :g:`Set Printing All.` + :g:`forall (x: t), P(x)` + +``:n:`` Any text using the notation syntax (``@id``, ``{+, …}``, etc.). + Use this to explain tactic equivalences. For example, you might write + this:: + + :n:`generalize @term as @ident` is just like :n:`generalize @term`, but + it names the introduced hypothesis :token:`ident`. + + Note that this example also uses ``:token:``. That's because ``ident`` is + defined in the Coq manual as a grammar production, and ``:token:`` + creates a link to that. When referring to a placeholder that happens to be + a grammar production, ``:token:`…``` is typically preferable to ``:n:`@…```. + +``:production:`` A grammar production not included in a ``productionlist`` directive. + Useful to informally introduce a production, as part of running text. + + Example:: + + :production:`string` indicates a quoted string. + + You're not likely to use this role very commonly; instead, use a + `production list + <http://www.sphinx-doc.org/en/stable/markup/para.html#directive-productionlist>`_ + and reference its tokens using ``:token:`…```. + +Common mistakes +=============== + +Improper nesting +---------------- + +DO + .. code:: + + .. cmd:: Foo @bar + + Foo the first instance of :token:`bar`\ s. + + .. cmdv:: Foo All + + Foo all the :token:`bar`\ s in + the current context + +DON'T + .. code:: + + .. cmd:: Foo @bar + + Foo the first instance of :token:`bar`\ s. + + .. cmdv:: Foo All + + Foo all the :token:`bar`\ s in + the current context + +You can set the ``report_undocumented_coq_objects`` setting in ``conf.py`` to ``"info"`` or ``"warning"`` to get a list of all Coq objects without a description. + +Overusing ``:token:`` +--------------------- + +DO + .. code:: + + This is equivalent to :n:`Axiom @ident : @term`. + +DON'T + .. code:: + + This is equivalent to ``Axiom`` :token:`ident` : :token:`term`. + +.. + +DO + .. code:: + + :n:`power_tac @term [@ltac]` + allows :tacn:`ring` and :tacn:`ring_simplify` to recognize … + +DON'T + .. code:: + + power_tac :n:`@term` [:n:`@ltac`] + allows :tacn:`ring` and :tacn:`ring_simplify` to recognize … + +.. + +DO + .. code:: + + :n:`name={*; attr}` + +DON'T + .. code:: + + ``name=``:n:`{*; attr}` + +Omitting annotations +-------------------- + +DO + .. code:: + + .. tacv:: assert @form as @simple_intropattern + +DON'T + .. code:: + + .. tacv:: assert form as simple_intropattern + +Using the ``.. coqtop::`` directive for syntax highlighting +----------------------------------------------------------- + +DO + .. code:: + + A tactic of the form: + + .. coqdoc:: + + do [ t1 | … | tn ]. + + is equivalent to the standard Ltac expression: + + .. coqdoc:: + + first [ t1 | … | tn ]. + +DON'T + .. code:: + + A tactic of the form: + + .. coqtop:: in + + do [ t1 | … | tn ]. + + is equivalent to the standard Ltac expression: + + .. coqtop:: in + + first [ t1 | … | tn ]. + +Overusing plain quotes +---------------------- + +DO + .. code:: + + The :tacn:`refine` tactic can raise the :exn:`Invalid argument` exception. + The term :g:`let a = 1 in a a` is ill-typed. + +DON'T + .. code:: + + The ``refine`` tactic can raise the ``Invalid argument`` exception. + The term ``let a = 1 in a a`` is ill-typed. + +Plain quotes produce plain text, without highlighting or cross-references. + +Overusing the ``example`` directive +----------------------------------- + +DO + .. code:: + + Here is a useful axiom: + + .. coqdoc:: + + Axiom proof_irrelevance : forall (P : Prop) (x y : P), x=y. + +DO + .. code:: + + .. example:: Using proof-irrelevance + + If you assume the axiom above, … + +DON'T + .. code:: + + Here is a useful axiom: + + .. example:: + + .. coqdoc:: + + Axiom proof_irrelevance : forall (P : Prop) (x y : P), x=y. + +Tips and tricks +=============== + +Nested lemmas +------------- + +The ``.. coqtop::`` directive does *not* reset Coq after running its contents. That is, the following will create two nested lemmas (which by default results in a failure):: + + .. coqtop:: all + + Lemma l1: 1 + 1 = 2. + + .. coqtop:: all + + Lemma l2: 2 + 2 <> 1. + +Add either ``abort`` to the first block or ``reset`` to the second block to avoid nesting lemmas. + +Abbreviations and macros +------------------------ + +Substitutions for specially-formatted names (like ``|Cic|``, ``|Coq|``, ``|CoqIDE|``, ``|Ltac|``, and ``|Gallina|``), along with some useful LaTeX macros, are defined in a `separate file </doc/sphinx/refman-preamble.rst>`_. This file is automatically included in all manual pages. + +Emacs +----- + +The ``dev/tools/coqdev.el`` folder contains a convenient Emacs function to quickly insert Sphinx roles and quotes. It takes a single character (one of ``gntm:```), and inserts one of ``:g:``, ``:n:``, ``:t:``, or an arbitrary role, or double quotes. You can also select a region of text, and wrap it in single or double backticks using that function. + +Use the following snippet to bind it to :kbd:`F12` in ``rst-mode``:: + + (with-eval-after-load 'rst + (define-key rst-mode-map (kbd "<f12>") #'coqdev-sphinx-rst-coq-action)) diff --git a/doc/sphinx/README.template.rst b/doc/sphinx/README.template.rst new file mode 100644 index 0000000000..78803a927f --- /dev/null +++ b/doc/sphinx/README.template.rst @@ -0,0 +1,293 @@ +============================= + Documenting Coq with Sphinx +============================= + +.. + README.rst is auto-generated from README.template.rst and the coqrst docs; + use ``doc/tools/coqrst/regen_readme.py`` to rebuild it. + +Coq's reference manual is written in `reStructuredText <http://www.sphinx-doc.org/en/master/usage/restructuredtext/basics.html>`_ (“reST”), and compiled with `Sphinx <http://www.sphinx-doc.org/en/master/>`_. + +In addition to standard reST directives (a directive is similar to a LaTeX environment) and roles (a role is similar to a LaTeX command), the ``coqrst`` plugin loaded by the documentation uses a custom *Coq domain* — a set of Coq-specific directives that define *objects* like tactics, commands (vernacs), warnings, etc. —, some custom *directives*, and a few custom *roles*. Finally, this manual uses a small DSL to describe tactic invocations and commands. + +Coq objects +=========== + +Our Coq domain define multiple `objects`_. Each object has a *signature* (think *type signature*), followed by an optional body (a description of that object). The following example defines two objects: a variant of the ``simpl`` tactic, and an error that it may raise:: + + .. tacv:: simpl @pattern at {+ @num} + :name: simpl_at + + This applies ``simpl`` only to the :n:`{+ @num}` occurrences of the subterms + matching :n:`@pattern` in the current goal. + + .. exn:: Too few occurrences + :undocumented: + +Objects are automatically collected into indices, and can be linked to using the role version of the object's directive. For example, you could link to the tactic variant above using ``:tacv:`simpl_at```, and to its exception using ``:exn:`Too few occurrences```. + +Names (link targets) are auto-generated for most simple objects, though they can always be overwritten using a ``:name:`` option, as shown above. + +- Options, errors, warnings have their name set to their signature, with ``...`` replacing all notation bits. For example, the auto-generated name of ``.. exn:: @qualid is not a module`` is ``... is not a module``, and a link to it would take the form ``:exn:`... is not a module```. +- Vernacs (commands) have their name set to the first word of their signature. For example, the auto-generated name of ``Axiom @ident : @term`` is ``Axiom``, and a link to it would take the form ``:cmd:`Axiom```. +- Vernac variants, tactic notations, and tactic variants do not have a default name. + +Most objects should have a body (i.e. a block of indented text following the signature, called “contents” in Sphinx terms). Undocumented objects should have the ``:undocumented:`` flag instead, as shown above. When multiple objects have a single description, they can be grouped into a single object, like this (semicolons can be used to separate the names of the objects; names starting with ``_`` will be omitted from the indexes):: + + .. cmdv:: Lemma @ident {? @binders} : @type + Remark @ident {? @binders} : @type + Fact @ident {? @binders} : @type + Corollary @ident {? @binders} : @type + Proposition @ident {? @binders} : @type + :name: Lemma; Remark; Fact; Corollary; Proposition + + These commands are all synonyms of :n:`Theorem @ident {? @binders } : type`. + +Notations +--------- + +The signatures of most objects can be written using a succinct DSL for Coq notations (think regular expressions written with a Lispy syntax). A typical signature might look like ``Hint Extern @num {? @pattern} => @tactic``, which means that the ``Hint Extern`` command takes a number (``num``), followed by an optional pattern, and a mandatory tactic. The language has the following constructs (the full grammar is in `TacticNotations.g </doc/tools/coqrst/notations/TacticNotations.g>`_): + +``@…`` + A placeholder (``@ident``, ``@num``, ``@tactic``\ …) + +``{? …}`` + an optional block + +``{* …}``, ``{+ …}`` + an optional (``*``) or mandatory (``+``) block that can be repeated, with repetitions separated by spaces + +``{*, …}``, ``{+, …}`` + an optional or mandatory repeatable block, with repetitions separated by commas + +``%|``, ``%{``, … + an escaped character (rendered without the leading ``%``) + +.. + FIXME document the new subscript support + +As an exercise, what do the following patterns mean? + +.. code:: + + pattern {+, @term {? at {+ @num}}} + generalize {+, @term at {+ @num} as @ident} + fix @ident @num with {+ (@ident {+ @binder} {? {struct @ident'}} : @type)} + +Objects +------- + +Here is the list of all objects of the Coq domain (The symbol :black_nib: indicates an object whose signature can be written using the notations DSL): + +[OBJECTS] + +Coq directives +============== + +In addition to the objects above, the ``coqrst`` Sphinx plugin defines the following directives: + +[DIRECTIVES] + +Coq roles +========= + +In addition to the objects and directives above, the ``coqrst`` Sphinx plugin defines the following roles: + +[ROLES] + +Common mistakes +=============== + +Improper nesting +---------------- + +DO + .. code:: + + .. cmd:: Foo @bar + + Foo the first instance of :token:`bar`\ s. + + .. cmdv:: Foo All + + Foo all the :token:`bar`\ s in + the current context + +DON'T + .. code:: + + .. cmd:: Foo @bar + + Foo the first instance of :token:`bar`\ s. + + .. cmdv:: Foo All + + Foo all the :token:`bar`\ s in + the current context + +You can set the ``report_undocumented_coq_objects`` setting in ``conf.py`` to ``"info"`` or ``"warning"`` to get a list of all Coq objects without a description. + +Overusing ``:token:`` +--------------------- + +DO + .. code:: + + This is equivalent to :n:`Axiom @ident : @term`. + +DON'T + .. code:: + + This is equivalent to ``Axiom`` :token:`ident` : :token:`term`. + +.. + +DO + .. code:: + + :n:`power_tac @term [@ltac]` + allows :tacn:`ring` and :tacn:`ring_simplify` to recognize … + +DON'T + .. code:: + + power_tac :n:`@term` [:n:`@ltac`] + allows :tacn:`ring` and :tacn:`ring_simplify` to recognize … + +.. + +DO + .. code:: + + :n:`name={*; attr}` + +DON'T + .. code:: + + ``name=``:n:`{*; attr}` + +Omitting annotations +-------------------- + +DO + .. code:: + + .. tacv:: assert @form as @simple_intropattern + +DON'T + .. code:: + + .. tacv:: assert form as simple_intropattern + +Using the ``.. coqtop::`` directive for syntax highlighting +----------------------------------------------------------- + +DO + .. code:: + + A tactic of the form: + + .. coqdoc:: + + do [ t1 | … | tn ]. + + is equivalent to the standard Ltac expression: + + .. coqdoc:: + + first [ t1 | … | tn ]. + +DON'T + .. code:: + + A tactic of the form: + + .. coqtop:: in + + do [ t1 | … | tn ]. + + is equivalent to the standard Ltac expression: + + .. coqtop:: in + + first [ t1 | … | tn ]. + +Overusing plain quotes +---------------------- + +DO + .. code:: + + The :tacn:`refine` tactic can raise the :exn:`Invalid argument` exception. + The term :g:`let a = 1 in a a` is ill-typed. + +DON'T + .. code:: + + The ``refine`` tactic can raise the ``Invalid argument`` exception. + The term ``let a = 1 in a a`` is ill-typed. + +Plain quotes produce plain text, without highlighting or cross-references. + +Overusing the ``example`` directive +----------------------------------- + +DO + .. code:: + + Here is a useful axiom: + + .. coqdoc:: + + Axiom proof_irrelevance : forall (P : Prop) (x y : P), x=y. + +DO + .. code:: + + .. example:: Using proof-irrelevance + + If you assume the axiom above, … + +DON'T + .. code:: + + Here is a useful axiom: + + .. example:: + + .. coqdoc:: + + Axiom proof_irrelevance : forall (P : Prop) (x y : P), x=y. + +Tips and tricks +=============== + +Nested lemmas +------------- + +The ``.. coqtop::`` directive does *not* reset Coq after running its contents. That is, the following will create two nested lemmas (which by default results in a failure):: + + .. coqtop:: all + + Lemma l1: 1 + 1 = 2. + + .. coqtop:: all + + Lemma l2: 2 + 2 <> 1. + +Add either ``abort`` to the first block or ``reset`` to the second block to avoid nesting lemmas. + +Abbreviations and macros +------------------------ + +Substitutions for specially-formatted names (like ``|Cic|``, ``|Coq|``, ``|CoqIDE|``, ``|Ltac|``, and ``|Gallina|``), along with some useful LaTeX macros, are defined in a `separate file </doc/sphinx/refman-preamble.rst>`_. This file is automatically included in all manual pages. + +Emacs +----- + +The ``dev/tools/coqdev.el`` folder contains a convenient Emacs function to quickly insert Sphinx roles and quotes. It takes a single character (one of ``gntm:```), and inserts one of ``:g:``, ``:n:``, ``:t:``, or an arbitrary role, or double quotes. You can also select a region of text, and wrap it in single or double backticks using that function. + +Use the following snippet to bind it to :kbd:`F12` in ``rst-mode``:: + + (with-eval-after-load 'rst + (define-key rst-mode-map (kbd "<f12>") #'coqdev-sphinx-rst-coq-action)) diff --git a/doc/sphinx/_static/CoqNotations.ttf b/doc/sphinx/_static/CoqNotations.ttf Binary files differnew file mode 100644 index 0000000000..da8f2850df --- /dev/null +++ b/doc/sphinx/_static/CoqNotations.ttf diff --git a/doc/sphinx/_static/ansi-dark.css b/doc/sphinx/_static/ansi-dark.css new file mode 100644 index 0000000000..a564fd70bb --- /dev/null +++ b/doc/sphinx/_static/ansi-dark.css @@ -0,0 +1,144 @@ +/************************************************************************/ +/* * The Coq Proof Assistant / The Coq Development Team */ +/* v * INRIA, CNRS and contributors - Copyright 1999-2018 */ +/* <O___,, * (see CREDITS file for the list of authors) */ +/* \VV/ **************************************************************/ +/* // * This file is distributed under the terms of the */ +/* * GNU Lesser General Public License Version 2.1 */ +/* * (see LICENSE file for the text of the license) */ +/************************************************************************/ +.ansi-bold { + font-weight: bold; +} + +.ansi-italic { + font-style: italic; +} + +.ansi-negative { + filter: invert(100%); +} + +.ansi-underline { + text-decoration: underline; +} + +.ansi-no-bold { + font-weight: normal; +} + +.ansi-no-italic { + font-style: normal; +} + +.ansi-no-negative { + filter: invert(0%); +} + +.ansi-no-underline { + text-decoration: none; +} + +.ansi-black { + color: #000000; +} + +.ansi-fg-red { + color: #b21717; +} + +.ansi-fg-green { + color: #17b217; +} + +.ansi-fg-yellow { + color: #b26717; +} + +.ansi-fg-blue { + color: #1717b2; +} + +.ansi-fg-magenta { + color: #b217b2; +} + +.ansi-fg-cyan { + color: #17b2b2; +} + +.ansi-fg-white { + color: #b2b2b2; +} + +.ansi-fg-default { + color: #404040; +} + +.ansi-fg-light-black { + color: #686868; +} + +.ansi-fg-light-red { + color: #ff5454; +} + +.ansi-fg-light-green { + color: #54ff54; +} + +.ansi-fg-light-yellow { + color: #ffff54; +} + +.ansi-fg-light-blue { + color: #5454ff; +} + +.ansi-fg-light-magenta { + color: #ff54ff; +} + +.ansi-fg-light-cyan { + color: #54ffff; +} + +.ansi-fg-light-white { + color: #ffffff; +} + +.ansi-bg-black { + background-color: #000000; +} + +.ansi-bg-red { + background-color: #b21717; +} + +.ansi-bg-green { + background-color: #17b217; +} + +.ansi-bg-yellow { + background-color: #b26717; +} + +.ansi-bg-blue { + background-color: #1717b2; +} + +.ansi-bg-magenta { + background-color: #b217b2; +} + +.ansi-bg-cyan { + background-color: #17b2b2; +} + +.ansi-bg-white { + background-color: #b2b2b2; +} + +.ansi-bg-default { + background-color: transparent; +} diff --git a/doc/sphinx/_static/ansi.css b/doc/sphinx/_static/ansi.css new file mode 100644 index 0000000000..26bd797709 --- /dev/null +++ b/doc/sphinx/_static/ansi.css @@ -0,0 +1,145 @@ +/************************************************************************/ +/* * The Coq Proof Assistant / The Coq Development Team */ +/* v * INRIA, CNRS and contributors - Copyright 1999-2018 */ +/* <O___,, * (see CREDITS file for the list of authors) */ +/* \VV/ **************************************************************/ +/* // * This file is distributed under the terms of the */ +/* * GNU Lesser General Public License Version 2.1 */ +/* * (see LICENSE file for the text of the license) */ +/************************************************************************/ +.ansi-bold { + font-weight: bold; +} + +.ansi-italic { + font-style: italic; +} + +.ansi-negative { + filter: invert(100%); +} + +.ansi-underline { + text-decoration: underline; +} + +.ansi-no-bold { + font-weight: normal; +} + +.ansi-no-italic { + font-style: normal; +} + +.ansi-no-negative { + filter: invert(0%); +} + +.ansi-no-underline { + text-decoration: none; +} + + +.ansi-fg-black { + color: #babdb6; +} + +.ansi-fg-red { + color: #a40000; +} + +.ansi-fg-green { + color: #4e9a06; +} + +.ansi-fg-yellow { + color: #ce5c00; +} + +.ansi-fg-blue { + color: #204a87; +} + +.ansi-fg-magenta { + color: #5c3566; +} + +.ansi-fg-cyan { + color: #8f5902; +} + +.ansi-fg-white { + color: #2e3436; +} + +.ansi-fg-light-black { + color: #d3d7cf; +} + +.ansi-fg-light-red { + color: #cc0000; +} + +.ansi-fg-light-green { + color: #346604; /* From tango.el */ +} + +.ansi-fg-light-yellow { + color: #f57900; +} + +.ansi-fg-light-blue { + color: #3465a4; +} + +.ansi-fg-light-magenta { + color: #75507b; +} + +.ansi-fg-light-cyan { + color: #c14d11; +} + +.ansi-fg-light-white { + color: #555753; +} + +.ansi-fg-default { + color: #eeeeec; +} + +.ansi-bg-black { + background-color: #babdb6; +} + +.ansi-bg-red { + background-color: #a40000; +} + +.ansi-bg-green { + background-color: #4e9a06; +} + +.ansi-bg-yellow { + background-color: #ce5c00; +} + +.ansi-bg-blue { + background-color: #204a87; +} + +.ansi-bg-magenta { + background-color: #5c3566; +} + +.ansi-bg-cyan { + background-color: #8f5902; +} + +.ansi-bg-white { + background-color: #2e3436; +} + +.ansi-bg-default { + background-color: transparent; +} diff --git a/doc/sphinx/_static/coqdoc.css b/doc/sphinx/_static/coqdoc.css new file mode 100644 index 0000000000..bbcc044a20 --- /dev/null +++ b/doc/sphinx/_static/coqdoc.css @@ -0,0 +1,68 @@ +/************************************************************************/ +/* * The Coq Proof Assistant / The Coq Development Team */ +/* v * INRIA, CNRS and contributors - Copyright 1999-2018 */ +/* <O___,, * (see CREDITS file for the list of authors) */ +/* \VV/ **************************************************************/ +/* // * This file is distributed under the terms of the */ +/* * GNU Lesser General Public License Version 2.1 */ +/* * (see LICENSE file for the text of the license) */ +/************************************************************************/ +/* Taken from CoqDoc's default stylesheet */ + +.coqdoc-constructor { + color: rgb(60%,0%,0%); +} + +.coqdoc-var { + color: rgb(40%,0%,40%); +} + +.coqdoc-variable { + color: rgb(40%,0%,40%); +} + +.coqdoc-definition { + color: rgb(0%,40%,0%); +} + +.coqdoc-abbreviation { + color: rgb(0%,40%,0%); +} + +.coqdoc-lemma { + color: rgb(0%,40%,0%); +} + +.coqdoc-instance { + color: rgb(0%,40%,0%); +} + +.coqdoc-projection { + color: rgb(0%,40%,0%); +} + +.coqdoc-method { + color: rgb(0%,40%,0%); +} + +.coqdoc-inductive { + color: rgb(0%,0%,80%); +} + +.coqdoc-record { + color: rgb(0%,0%,80%); +} + +.coqdoc-class { + color: rgb(0%,0%,80%); +} + +.coqdoc-keyword { + color : #cf1d1d; +} + +/* Custom additions */ + +.coqdoc-tactic { + font-weight: bold; +} diff --git a/doc/sphinx/_static/coqide-queries.png b/doc/sphinx/_static/coqide-queries.png Binary files differnew file mode 100644 index 0000000000..7a46ac4e68 --- /dev/null +++ b/doc/sphinx/_static/coqide-queries.png diff --git a/doc/sphinx/_static/coqide.png b/doc/sphinx/_static/coqide.png Binary files differnew file mode 100644 index 0000000000..e300401c9f --- /dev/null +++ b/doc/sphinx/_static/coqide.png diff --git a/doc/sphinx/_static/coqnotations.sty b/doc/sphinx/_static/coqnotations.sty new file mode 100644 index 0000000000..75eac1f724 --- /dev/null +++ b/doc/sphinx/_static/coqnotations.sty @@ -0,0 +1,50 @@ +% The LaTeX generator wraps all custom spans in \DUrole{class}{contents}. That +% command then checks for another command called \DUroleclass. + +% Most of our CSS class names have dashes, so we need ‘\csname … \endcsname’ + +% <magic> +% \def\newcssclass#1#2{\expandafter\def\csname DUrole#1\endcsname ##1{#2}} +% </magic> + +\RequirePackage{adjustbox} +\RequirePackage{xcolor} +\RequirePackage{amsmath} + +\definecolor{nbordercolor}{HTML}{AAAAAA} +\definecolor{nbgcolor}{HTML}{EAEAEA} +\definecolor{nholecolor}{HTML}{4E9A06} + +\newlength{\nscriptsize} +\setlength{\nscriptsize}{0.8em} + +\newcommand*{\scriptsmallsquarebox}[1]{% + % Force width + \makebox[\nscriptsize]{% + % Force height and center vertically + \raisebox{\dimexpr .5\nscriptsize - .5\height \relax}[\nscriptsize][0pt]{% + % Cancel depth + \raisebox{\depth}{#1}}}} +\newcommand*{\nscriptdecoratedbox}[2][]{\adjustbox{cfbox=nbordercolor 0.5pt 0pt,bgcolor=nbgcolor}{#2}} +\newcommand*{\nscriptbox}[1]{\nscriptdecoratedbox{\scriptsmallsquarebox{\textbf{#1}}}} +\newcommand*{\nscript}[2]{\text{\hspace{-.5\nscriptsize}\raisebox{-#1\nscriptsize}{\nscriptbox{\small#2}}}} +\newcommand*{\nsup}[1]{^{\nscript{0.15}{#1}}} +\newcommand*{\nsub}[1]{_{\nscript{0.35}{#1}}} +\newcommand*{\nnotation}[1]{#1} +\newcommand*{\nrepeat}[1]{\text{\adjustbox{cfbox=nbordercolor 0.5pt 2pt,bgcolor=nbgcolor}{#1\hspace{.5\nscriptsize}}}} +\newcommand*{\nwrapper}[1]{\ensuremath{\displaystyle#1}} % https://tex.stackexchange.com/questions/310877/ +\newcommand*{\nhole}[1]{\textit{\color{nholecolor}#1}} + +% <magic> +% Make it easier to define new commands matching CSS classes +\newcommand{\newcssclass}[2]{% + \expandafter\def\csname DUrole#1\endcsname##1{#2} +} +% </magic> + +\newcssclass{notation-sup}{\nsup{#1}} +\newcssclass{notation-sub}{\nsub{#1}} +\newcssclass{notation}{\nnotation{#1}} +\newcssclass{repeat}{\nrepeat{#1}} +\newcssclass{repeat-wrapper}{\nwrapper{#1}} +\newcssclass{hole}{\nhole{#1}} diff --git a/doc/sphinx/_static/diffs-coqide-compacted.png b/doc/sphinx/_static/diffs-coqide-compacted.png Binary files differnew file mode 100644 index 0000000000..b64ffeb269 --- /dev/null +++ b/doc/sphinx/_static/diffs-coqide-compacted.png diff --git a/doc/sphinx/_static/diffs-coqide-multigoal.png b/doc/sphinx/_static/diffs-coqide-multigoal.png Binary files differnew file mode 100644 index 0000000000..4020279267 --- /dev/null +++ b/doc/sphinx/_static/diffs-coqide-multigoal.png diff --git a/doc/sphinx/_static/diffs-coqide-on.png b/doc/sphinx/_static/diffs-coqide-on.png Binary files differnew file mode 100644 index 0000000000..f270397ea3 --- /dev/null +++ b/doc/sphinx/_static/diffs-coqide-on.png diff --git a/doc/sphinx/_static/diffs-coqide-removed.png b/doc/sphinx/_static/diffs-coqide-removed.png Binary files differnew file mode 100644 index 0000000000..8f2e71fdc8 --- /dev/null +++ b/doc/sphinx/_static/diffs-coqide-removed.png diff --git a/doc/sphinx/_static/diffs-coqtop-compacted.png b/doc/sphinx/_static/diffs-coqtop-compacted.png Binary files differnew file mode 100644 index 0000000000..b37f0a6771 --- /dev/null +++ b/doc/sphinx/_static/diffs-coqtop-compacted.png diff --git a/doc/sphinx/_static/diffs-coqtop-multigoal.png b/doc/sphinx/_static/diffs-coqtop-multigoal.png Binary files differnew file mode 100644 index 0000000000..cfedde02ac --- /dev/null +++ b/doc/sphinx/_static/diffs-coqtop-multigoal.png diff --git a/doc/sphinx/_static/diffs-coqtop-on.png b/doc/sphinx/_static/diffs-coqtop-on.png Binary files differnew file mode 100644 index 0000000000..bdfcf0af1a --- /dev/null +++ b/doc/sphinx/_static/diffs-coqtop-on.png diff --git a/doc/sphinx/_static/diffs-coqtop-on3.png b/doc/sphinx/_static/diffs-coqtop-on3.png Binary files differnew file mode 100644 index 0000000000..63ff869432 --- /dev/null +++ b/doc/sphinx/_static/diffs-coqtop-on3.png diff --git a/doc/sphinx/_static/diffs-error-message.png b/doc/sphinx/_static/diffs-error-message.png Binary files differnew file mode 100644 index 0000000000..6733d9c6a9 --- /dev/null +++ b/doc/sphinx/_static/diffs-error-message.png diff --git a/doc/sphinx/_static/notations.css b/doc/sphinx/_static/notations.css new file mode 100644 index 0000000000..dcb47d1786 --- /dev/null +++ b/doc/sphinx/_static/notations.css @@ -0,0 +1,173 @@ +/************************************************************************/ +/* * The Coq Proof Assistant / The Coq Development Team */ +/* v * INRIA, CNRS and contributors - Copyright 1999-2018 */ +/* <O___,, * (see CREDITS file for the list of authors) */ +/* \VV/ **************************************************************/ +/* // * This file is distributed under the terms of the */ +/* * GNU Lesser General Public License Version 2.1 */ +/* * (see LICENSE file for the text of the license) */ +/************************************************************************/ +.notation { + /* font-family: "Ubuntu Mono", "Consolas", monospace; */ + white-space: pre-wrap; +} + +.notation .notation-sup { + top: -0.4em; +} + +.notation .notation-sub { + bottom: -0.4em; + border-radius: 1rem; +} + +@font-face { /* This font has been edited to center all characters */ + font-family: 'CoqNotations'; + font-style: normal; + font-weight: 800; + src: local('CoqNotations'), url(./CoqNotations.ttf) format('truetype'); +} + +.notation .notation-sup, .notation .notation-sub { + background: #EAEAEA; + border: 1px solid #AAA; + color: black; + /* cursor: help; */ + display: inline-block; + font-size: 0.45em; + font-weight: bolder; + font-family: CoqNotations, monospace; + height: 2.2em; + line-height: 1.6em; + position: absolute; + right: -1em; /* half of the width */ + text-align: center; + width: 2.2em; +} + +.notation .repeat { + background: #EAEAEA; + border: 1px solid #AAA; + display: inline-block; + padding-right: 0.6em; /* Space for the left half of the sub- and sup-scripts */ + padding-left: 0.2em; + margin: 0.25em 0; +} + +.notation .repeat-wrapper { + display: inline-block; + position: relative; + margin-right: 0.4em; /* Space for the right half of the sub- and sup-scripts */ +} + +.notation .hole, .std-token .pre { + color: #4e9a06; + font-style: italic; + font-weight: bold; +} + +/***********************/ +/* Small extra classes */ +/***********************/ + +.math-preamble { + display: none; +} + +.inline-grammar-production { + font-weight: bold; +} + +/************************/ +/* Coqtop IO and Coqdoc */ +/************************/ + +.coqtop dd, .ansi-bg-default { + background: #eeeeee !important; +} + +.coqtop dd, .ansi-fg-default { + color: #2e3436 !important; +} + +.coqtop dt { /* Questions */ + background: none !important; + color: #333 !important; + font-weight: normal !important; + padding: 0 !important; + margin: 0 !important; +} + +.coqtop dd { /* Responses */ + padding: 0.5em; + margin-left: 0 !important; + margin-top: 0.5em !important; +} + +.coqdoc, .coqtop dl { + margin: 12px; /* Copied from RTD theme */ +} + +.coqdoc { + display: block; + white-space: pre; +} + +.coqtop dt, .coqtop dd { + border: none !important; + display: block !important; +} + +.coqtop.coqtop-hidden, dd.coqtop-hidden, dt.coqtop-hidden { /* Overqualifying for precedence */ + display: none !important; +} + +/* FIXME: Specific to the RTD theme */ +.coqdoc, .coqtop dt, .coqtop dd, pre { /* pre added because of production lists */ + font-family: Consolas,"Andale Mono WT","Andale Mono","Lucida Console","Lucida Sans Typewriter","DejaVu Sans Mono","Bitstream Vera Sans Mono","Liberation Mono","Nimbus Mono L",Monaco,"Courier New",Courier,monospace !important; /* Copied from RTD theme */ + font-size: 12px !important; /* Copied from RTD theme */ + line-height: 1.5 !important; /* Copied from RTD theme */ + white-space: pre; +} + +/*************/ +/* Overrides */ +/*************/ + +.rst-content table.docutils td, .rst-content table.docutils th { + padding: 8px; /* Reduce horizontal padding */ + border-left: none; + border-right: none; +} + +/* We can't display nested blocks otherwise */ +code, .rst-content tt, .rst-content code { + background: transparent !important; + border: none !important; + font-size: inherit !important; +} + +code { + padding: 0 !important; /* This padding doesn't make sense without a border */ +} + +dt > .property { + margin-right: 0.25em; +} + +.icon-home:visited { + color: #FFFFFF; +} + +/* Pygments for Coq is confused by ‘…’ */ +code span.error { + background: inherit !important; + line-height: inherit !important; + margin-bottom: 0 !important; + padding: 0 !important; +} + +/* Red is too aggressive */ +.rst-content tt.literal, .rst-content tt.literal, .rst-content code.literal { + color: inherit !important; +} diff --git a/doc/sphinx/_static/notations.js b/doc/sphinx/_static/notations.js new file mode 100644 index 0000000000..eb7f211e8b --- /dev/null +++ b/doc/sphinx/_static/notations.js @@ -0,0 +1,43 @@ +/************************************************************************/ +/* * The Coq Proof Assistant / The Coq Development Team */ +/* v * INRIA, CNRS and contributors - Copyright 1999-2018 */ +/* <O___,, * (see CREDITS file for the list of authors) */ +/* \VV/ **************************************************************/ +/* // * This file is distributed under the terms of the */ +/* * GNU Lesser General Public License Version 2.1 */ +/* * (see LICENSE file for the text of the license) */ +/************************************************************************/ +function annotateSup(marker) { + switch (marker) { + case "?": + return "This block is optional."; + case "*": + return "This block is optional, and may be repeated."; + case "+": + return "This block may be repeated."; + } +} + +function annotateSub(separator) { + return "Use “" + separator + "” to separate repetitions of this block."; +} + +// function translatePunctuation(original) { +// var mappings = { ",": "⸴" }; // ， +// return mappings[original] || original; +// } + +function annotateNotations () { + $(".repeat-wrapper > sup") + .attr("data-hint", function() { + return annotateSup($(this).text()); + }).addClass("hint--top hint--rounded"); + + $(".repeat-wrapper > sub") + .attr("data-hint", function() { + return annotateSub($(this).text()); + }).addClass("hint--bottom hint--rounded"); + //.text(function(i, text) { return translatePunctuation(text); }); +} + +$(annotateNotations); diff --git a/doc/sphinx/_static/pre-text.css b/doc/sphinx/_static/pre-text.css new file mode 100644 index 0000000000..38d81abefe --- /dev/null +++ b/doc/sphinx/_static/pre-text.css @@ -0,0 +1,29 @@ +/************************************************************************/ +/* * The Coq Proof Assistant / The Coq Development Team */ +/* v * INRIA, CNRS and contributors - Copyright 1999-2018 */ +/* <O___,, * (see CREDITS file for the list of authors) */ +/* \VV/ **************************************************************/ +/* // * This file is distributed under the terms of the */ +/* * GNU Lesser General Public License Version 2.1 */ +/* * (see LICENSE file for the text of the license) */ +/************************************************************************/ +/* Formatting for PRE (literal) text in .rst files */ + +.line-block { + background-color: rgb(80%,90%,80%); + margin: 0px; + margin-top: 0px; + margin-right: 16px; + margin-bottom: 20px; + padding-left: 4px; + padding-top: 4px; + padding-bottom: 4px; +} + +.line-block cite { + font-size: 90%; +} + +.pre { + font-size: 90%; +} diff --git a/doc/sphinx/addendum/canonical-structures.rst b/doc/sphinx/addendum/canonical-structures.rst new file mode 100644 index 0000000000..dd21ea09bd --- /dev/null +++ b/doc/sphinx/addendum/canonical-structures.rst @@ -0,0 +1,438 @@ +.. _canonicalstructures: + +Canonical Structures +====================== + +:Authors: Assia Mahboubi and Enrico Tassi + +This chapter explains the basics of canonical structures and how they can be used +to overload notations and build a hierarchy of algebraic structures. The +examples are taken from :cite:`CSwcu`. We invite the interested reader to refer +to this paper for all the details that are omitted here for brevity. The +interested reader shall also find in :cite:`CSlessadhoc` a detailed description +of another, complementary, use of canonical structures: advanced proof search. +This latter papers also presents many techniques one can employ to tune the +inference of canonical structures. + + +Notation overloading +------------------------- + +We build an infix notation == for a comparison predicate. Such +notation will be overloaded, and its meaning will depend on the types +of the terms that are compared. + +.. coqtop:: all + + Module EQ. + Record class (T : Type) := Class { cmp : T -> T -> Prop }. + Structure type := Pack { obj : Type; class_of : class obj }. + Definition op (e : type) : obj e -> obj e -> Prop := + let 'Pack _ (Class _ the_cmp) := e in the_cmp. + Check op. + Arguments op {e} x y : simpl never. + Arguments Class {T} cmp. + Module theory. + Notation "x == y" := (op x y) (at level 70). + End theory. + End EQ. + +We use Coq modules as namespaces. This allows us to follow the same +pattern and naming convention for the rest of the chapter. The base +namespace contains the definitions of the algebraic structure. To +keep the example small, the algebraic structure ``EQ.type`` we are +defining is very simplistic, and characterizes terms on which a binary +relation is defined, without requiring such relation to validate any +property. The inner theory module contains the overloaded notation ``==`` +and will eventually contain lemmas holding all the instances of the +algebraic structure (in this case there are no lemmas). + +Note that in practice the user may want to declare ``EQ.obj`` as a +coercion, but we will not do that here. + +The following line tests that, when we assume a type ``e`` that is in +theEQ class, we can relate two of its objects with ``==``. + +.. coqtop:: all + + Import EQ.theory. + Check forall (e : EQ.type) (a b : EQ.obj e), a == b. + +Still, no concrete type is in the ``EQ`` class. + +.. coqtop:: all + + Fail Check 3 == 3. + +We amend that by equipping ``nat`` with a comparison relation. + +.. coqtop:: all + + Definition nat_eq (x y : nat) := Nat.compare x y = Eq. + Definition nat_EQcl : EQ.class nat := EQ.Class nat_eq. + Canonical Structure nat_EQty : EQ.type := EQ.Pack nat nat_EQcl. + Check 3 == 3. + Eval compute in 3 == 4. + +This last test shows that |Coq| is now not only able to type check ``3 == 3``, +but also that the infix relation was bound to the ``nat_eq`` relation. +This relation is selected whenever ``==`` is used on terms of type nat. +This can be read in the line declaring the canonical structure +``nat_EQty``, where the first argument to ``Pack`` is the key and its second +argument a group of canonical values associated to the key. In this +case we associate to nat only one canonical value (since its class, +``nat_EQcl`` has just one member). The use of the projection ``op`` requires +its argument to be in the class ``EQ``, and uses such a member (function) +to actually compare its arguments. + +Similarly, we could equip any other type with a comparison relation, +and use the ``==`` notation on terms of this type. + + +Derived Canonical Structures +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +We know how to use ``==`` on base types, like ``nat``, ``bool``, ``Z``. Here we show +how to deal with type constructors, i.e. how to make the following +example work: + + +.. coqtop:: all + + Fail Check forall (e : EQ.type) (a b : EQ.obj e), (a, b) == (a, b). + +The error message is telling that |Coq| has no idea on how to compare +pairs of objects. The following construction is telling Coq exactly +how to do that. + +.. coqtop:: all + + Definition pair_eq (e1 e2 : EQ.type) (x y : EQ.obj e1 * EQ.obj e2) := + fst x == fst y /\ snd x == snd y. + + Definition pair_EQcl e1 e2 := EQ.Class (pair_eq e1 e2). + + Canonical Structure pair_EQty (e1 e2 : EQ.type) : EQ.type := + EQ.Pack (EQ.obj e1 * EQ.obj e2) (pair_EQcl e1 e2). + + Check forall (e : EQ.type) (a b : EQ.obj e), (a, b) == (a, b). + + Check forall n m : nat, (3, 4) == (n, m). + +Thanks to the ``pair_EQty`` declaration, |Coq| is able to build a comparison +relation for pairs whenever it is able to build a comparison relation +for each component of the pair. The declaration associates to the key ``*`` +(the type constructor of pairs) the canonical comparison +relation ``pair_eq`` whenever the type constructor ``*`` is applied to two +types being themselves in the ``EQ`` class. + +Hierarchy of structures +---------------------------- + +To get to an interesting example we need another base class to be +available. We choose the class of types that are equipped with an +order relation, to which we associate the infix ``<=`` notation. + +.. coqtop:: all + + Module LE. + + Record class T := Class { cmp : T -> T -> Prop }. + + Structure type := Pack { obj : Type; class_of : class obj }. + + Definition op (e : type) : obj e -> obj e -> Prop := + let 'Pack _ (Class _ f) := e in f. + + Arguments op {_} x y : simpl never. + + Arguments Class {T} cmp. + + Module theory. + + Notation "x <= y" := (op x y) (at level 70). + + End theory. + + End LE. + +As before we register a canonical ``LE`` class for ``nat``. + +.. coqtop:: all + + Import LE.theory. + + Definition nat_le x y := Nat.compare x y <> Gt. + + Definition nat_LEcl : LE.class nat := LE.Class nat_le. + + Canonical Structure nat_LEty : LE.type := LE.Pack nat nat_LEcl. + +And we enable |Coq| to relate pair of terms with ``<=``. + +.. coqtop:: all + + Definition pair_le e1 e2 (x y : LE.obj e1 * LE.obj e2) := + fst x <= fst y /\ snd x <= snd y. + + Definition pair_LEcl e1 e2 := LE.Class (pair_le e1 e2). + + Canonical Structure pair_LEty (e1 e2 : LE.type) : LE.type := + LE.Pack (LE.obj e1 * LE.obj e2) (pair_LEcl e1 e2). + + Check (3,4,5) <= (3,4,5). + +At the current stage we can use ``==`` and ``<=`` on concrete types, like +tuples of natural numbers, but we can’t develop an algebraic theory +over the types that are equipped with both relations. + +.. coqtop:: all + + Check 2 <= 3 /\ 2 == 2. + + Fail Check forall (e : EQ.type) (x y : EQ.obj e), x <= y -> y <= x -> x == y. + + Fail Check forall (e : LE.type) (x y : LE.obj e), x <= y -> y <= x -> x == y. + +We need to define a new class that inherits from both ``EQ`` and ``LE``. + + +.. coqtop:: all + + Module LEQ. + + Record mixin (e : EQ.type) (le : EQ.obj e -> EQ.obj e -> Prop) := + Mixin { compat : forall x y : EQ.obj e, le x y /\ le y x <-> x == y }. + + Record class T := Class { + EQ_class : EQ.class T; + LE_class : LE.class T; + extra : mixin (EQ.Pack T EQ_class) (LE.cmp T LE_class) }. + + Structure type := _Pack { obj : Type; class_of : class obj }. + + Arguments Mixin {e le} _. + + Arguments Class {T} _ _ _. + +The mixin component of the ``LEQ`` class contains all the extra content we +are adding to ``EQ`` and ``LE``. In particular it contains the requirement +that the two relations we are combining are compatible. + +Unfortunately there is still an obstacle to developing the algebraic +theory of this new class. + +.. coqtop:: all + + Module theory. + + Fail Check forall (le : type) (n m : obj le), n <= m -> n <= m -> n == m. + + +The problem is that the two classes ``LE`` and ``LEQ`` are not yet related by +a subclass relation. In other words |Coq| does not see that an object of +the ``LEQ`` class is also an object of the ``LE`` class. + +The following two constructions tell |Coq| how to canonically build the +``LE.type`` and ``EQ.type`` structure given an ``LEQ.type`` structure on the same +type. + +.. coqtop:: all + + Definition to_EQ (e : type) : EQ.type := + EQ.Pack (obj e) (EQ_class _ (class_of e)). + + Canonical Structure to_EQ. + + Definition to_LE (e : type) : LE.type := + LE.Pack (obj e) (LE_class _ (class_of e)). + + Canonical Structure to_LE. + +We can now formulate out first theorem on the objects of the ``LEQ`` +structure. + +.. coqtop:: all + + Lemma lele_eq (e : type) (x y : obj e) : x <= y -> y <= x -> x == y. + + now intros; apply (compat _ _ (extra _ (class_of e)) x y); split. + + Qed. + + Arguments lele_eq {e} x y _ _. + + End theory. + + End LEQ. + + Import LEQ.theory. + + Check lele_eq. + +Of course one would like to apply results proved in the algebraic +setting to any concrete instate of the algebraic structure. + +.. coqtop:: all + + Example test_algebraic (n m : nat) : n <= m -> m <= n -> n == m. + + Fail apply (lele_eq n m). + + Abort. + + Example test_algebraic2 (l1 l2 : LEQ.type) (n m : LEQ.obj l1 * LEQ.obj l2) : + n <= m -> m <= n -> n == m. + + Fail apply (lele_eq n m). + + Abort. + +Again one has to tell |Coq| that the type ``nat`` is in the ``LEQ`` class, and +how the type constructor ``*`` interacts with the ``LEQ`` class. In the +following proofs are omitted for brevity. + +.. coqtop:: all + + Lemma nat_LEQ_compat (n m : nat) : n <= m /\ m <= n <-> n == m. + + Admitted. + + Definition nat_LEQmx := LEQ.Mixin nat_LEQ_compat. + + Lemma pair_LEQ_compat (l1 l2 : LEQ.type) (n m : LEQ.obj l1 * LEQ.obj l2) : + n <= m /\ m <= n <-> n == m. + + Admitted. + + Definition pair_LEQmx l1 l2 := LEQ.Mixin (pair_LEQ_compat l1 l2). + +The following script registers an ``LEQ`` class for ``nat`` and for the type +constructor ``*``. It also tests that they work as expected. + +Unfortunately, these declarations are very verbose. In the following +subsection we show how to make them more compact. + +.. FIXME shouldn't warn + +.. coqtop:: all warn + + Module Add_instance_attempt. + + Canonical Structure nat_LEQty : LEQ.type := + LEQ._Pack nat (LEQ.Class nat_EQcl nat_LEcl nat_LEQmx). + + Canonical Structure pair_LEQty (l1 l2 : LEQ.type) : LEQ.type := + LEQ._Pack (LEQ.obj l1 * LEQ.obj l2) + (LEQ.Class + (EQ.class_of (pair_EQty (to_EQ l1) (to_EQ l2))) + (LE.class_of (pair_LEty (to_LE l1) (to_LE l2))) + (pair_LEQmx l1 l2)). + + Example test_algebraic (n m : nat) : n <= m -> m <= n -> n == m. + + now apply (lele_eq n m). + + Qed. + + Example test_algebraic2 (n m : nat * nat) : n <= m -> m <= n -> n == m. + + now apply (lele_eq n m). Qed. + + End Add_instance_attempt. + +Note that no direct proof of ``n <= m -> m <= n -> n == m`` is provided by +the user for ``n`` and m of type ``nat * nat``. What the user provides is a +proof of this statement for ``n`` and ``m`` of type ``nat`` and a proof that the +pair constructor preserves this property. The combination of these two +facts is a simple form of proof search that |Coq| performs automatically +while inferring canonical structures. + +Compact declaration of Canonical Structures +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +We need some infrastructure for that. + +.. coqtop:: all + + Require Import Strings.String. + + Module infrastructure. + + Inductive phantom {T : Type} (t : T) : Type := Phantom. + + Definition unify {T1 T2} (t1 : T1) (t2 : T2) (s : option string) := + phantom t1 -> phantom t2. + + Definition id {T} {t : T} (x : phantom t) := x. + + Notation "[find v | t1 ~ t2 ] p" := (fun v (_ : unify t1 t2 None) => p) + (at level 50, v ident, only parsing). + + Notation "[find v | t1 ~ t2 | s ] p" := (fun v (_ : unify t1 t2 (Some s)) => p) + (at level 50, v ident, only parsing). + + Notation "'Error : t : s" := (unify _ t (Some s)) + (at level 50, format "''Error' : t : s"). + + Open Scope string_scope. + + End infrastructure. + +To explain the notation ``[find v | t1 ~ t2]`` let us pick one of its +instances: ``[find e | EQ.obj e ~ T | "is not an EQ.type" ]``. It should be +read as: “find a class e such that its objects have type T or fail +with message "T is not an EQ.type"”. + +The other utilities are used to ask |Coq| to solve a specific unification +problem, that will in turn require the inference of some canonical structures. +They are explained in more details in :cite:`CSwcu`. + +We now have all we need to create a compact “packager” to declare +instances of the ``LEQ`` class. + +.. coqtop:: all + + Import infrastructure. + + Definition packager T e0 le0 (m0 : LEQ.mixin e0 le0) := + [find e | EQ.obj e ~ T | "is not an EQ.type" ] + [find o | LE.obj o ~ T | "is not an LE.type" ] + [find ce | EQ.class_of e ~ ce ] + [find co | LE.class_of o ~ co ] + [find m | m ~ m0 | "is not the right mixin" ] + LEQ._Pack T (LEQ.Class ce co m). + + Notation Pack T m := (packager T _ _ m _ id _ id _ id _ id _ id). + +The object ``Pack`` takes a type ``T`` (the key) and a mixin ``m``. It infers all +the other pieces of the class ``LEQ`` and declares them as canonical +values associated to the ``T`` key. All in all, the only new piece of +information we add in the ``LEQ`` class is the mixin, all the rest is +already canonical for ``T`` and hence can be inferred by |Coq|. + +``Pack`` is a notation, hence it is not type checked at the time of its +declaration. It will be type checked when it is used, an in that case ``T`` is +going to be a concrete type. The odd arguments ``_`` and ``id`` we pass to the +packager represent respectively the classes to be inferred (like ``e``, ``o``, +etc) and a token (``id``) to force their inference. Again, for all the details +the reader can refer to :cite:`CSwcu`. + +The declaration of canonical instances can now be way more compact: + +.. FIXME should not warn + +.. coqtop:: all warn + + Canonical Structure nat_LEQty := Eval hnf in Pack nat nat_LEQmx. + + Canonical Structure pair_LEQty (l1 l2 : LEQ.type) := + Eval hnf in Pack (LEQ.obj l1 * LEQ.obj l2) (pair_LEQmx l1 l2). + +Error messages are also quite intelligible (if one skips to the end of +the message). + +.. coqtop:: all + + Fail Canonical Structure err := Eval hnf in Pack bool nat_LEQmx. + diff --git a/doc/sphinx/addendum/extended-pattern-matching.rst b/doc/sphinx/addendum/extended-pattern-matching.rst new file mode 100644 index 0000000000..e882ce6e88 --- /dev/null +++ b/doc/sphinx/addendum/extended-pattern-matching.rst @@ -0,0 +1,619 @@ +.. _extendedpatternmatching: + +Extended pattern matching +========================= + +:Authors: Cristina Cornes and Hugo Herbelin + +.. TODO links to figures + +This section describes the full form of pattern matching in |Coq| terms. + +.. |rhs| replace:: right hand sides + +Patterns +-------- + +The full syntax of match is presented in Figures 1.1 and 1.2. +Identifiers in patterns are either constructor names or variables. Any +identifier that is not the constructor of an inductive or co-inductive +type is considered to be a variable. A variable name cannot occur more +than once in a given pattern. It is recommended to start variable +names by a lowercase letter. + +If a pattern has the form ``(c x)`` where ``c`` is a constructor symbol and x +is a linear vector of (distinct) variables, it is called *simple*: it +is the kind of pattern recognized by the basic version of match. On +the opposite, if it is a variable ``x`` or has the form ``(c p)`` with ``p`` not +only made of variables, the pattern is called *nested*. + +A variable pattern matches any value, and the identifier is bound to +that value. The pattern “``_``” (called “don't care” or “wildcard” symbol) +also matches any value, but does not bind anything. It may occur an +arbitrary number of times in a pattern. Alias patterns written +:n:`(@pattern as @ident)` are also accepted. This pattern matches the +same values as :token:`pattern` does and :token:`ident` is bound to the matched +value. A pattern of the form :n:`@pattern | @pattern` is called disjunctive. A +list of patterns separated with commas is also considered as a pattern +and is called *multiple pattern*. However multiple patterns can only +occur at the root of pattern matching equations. Disjunctions of +*multiple patterns* are allowed though. + +Since extended ``match`` expressions are compiled into the primitive ones, +the expressiveness of the theory remains the same. Once parsing has finished +only simple patterns remain. The original nesting of the ``match`` expressions +is recovered at printing time. An easy way to see the result +of the expansion is to toggle off the nesting performed at printing +(use here :flag:`Printing Matching`), then by printing the term with :cmd:`Print` +if the term is a constant, or using the command :cmd:`Check`. + +The extended ``match`` still accepts an optional *elimination predicate* +given after the keyword ``return``. Given a pattern matching expression, +if all the right-hand-sides of ``=>`` have the same +type, then this type can be sometimes synthesized, and so we can omit +the return part. Otherwise the predicate after return has to be +provided, like for the basicmatch. + +Let us illustrate through examples the different aspects of extended +pattern matching. Consider for example the function that computes the +maximum of two natural numbers. We can write it in primitive syntax +by: + +.. coqtop:: in + + Fixpoint max (n m:nat) {struct m} : nat := + match n with + | O => m + | S n' => match m with + | O => S n' + | S m' => S (max n' m') + end + end. + +Multiple patterns +----------------- + +Using multiple patterns in the definition of ``max`` lets us write: + +.. coqtop:: in reset + + Fixpoint max (n m:nat) {struct m} : nat := + match n, m with + | O, _ => m + | S n', O => S n' + | S n', S m' => S (max n' m') + end. + +which will be compiled into the previous form. + +The pattern matching compilation strategy examines patterns from left +to right. A match expression is generated **only** when there is at least +one constructor in the column of patterns. E.g. the following example +does not build a match expression. + +.. coqtop:: all + + Check (fun x:nat => match x return nat with + | y => y + end). + + +Aliasing subpatterns +-------------------- + +We can also use :n:`as @ident` to associate a name to a sub-pattern: + +.. coqtop:: in reset + + Fixpoint max (n m:nat) {struct n} : nat := + match n, m with + | O, _ => m + | S n' as p, O => p + | S n', S m' => S (max n' m') + end. + +Nested patterns +--------------- + +Here is now an example of nested patterns: + +.. coqtop:: in + + Fixpoint even (n:nat) : bool := + match n with + | O => true + | S O => false + | S (S n') => even n' + end. + +This is compiled into: + +.. coqtop:: all + + Unset Printing Matching. + Print even. + +.. coqtop:: none + + Set Printing Matching. + +In the previous examples patterns do not conflict with, but sometimes +it is comfortable to write patterns that admit a non trivial +superposition. Consider the boolean function :g:`lef` that given two +natural numbers yields :g:`true` if the first one is less or equal than the +second one and :g:`false` otherwise. We can write it as follows: + +.. coqtop:: in + + Fixpoint lef (n m:nat) {struct m} : bool := + match n, m with + | O, x => true + | x, O => false + | S n, S m => lef n m + end. + +Note that the first and the second multiple pattern overlap because +the couple of values ``O O`` matches both. Thus, what is the result of the +function on those values? To eliminate ambiguity we use the *textual +priority rule:* we consider patterns to be ordered from top to bottom. A +value is matched by the pattern at the ith row if and only if it is +not matched by some pattern from a previous row. Thus in the example, ``O O`` +is matched by the first pattern, and so :g:`(lef O O)` yields true. + +Another way to write this function is: + +.. coqtop:: in reset + + Fixpoint lef (n m:nat) {struct m} : bool := + match n, m with + | O, x => true + | S n, S m => lef n m + | _, _ => false + end. + +Here the last pattern superposes with the first two. Because of the +priority rule, the last pattern will be used only for values that do +not match neither the first nor the second one. + +Terms with useless patterns are not accepted by the system. Here is an +example: + +.. coqtop:: all + + Fail Check (fun x:nat => + match x with + | O => true + | S _ => false + | x => true + end). + + +Disjunctive patterns +-------------------- + +Multiple patterns that share the same right-hand-side can be +factorized using the notation :n:`{+| @mult_pattern}`. For +instance, :g:`max` can be rewritten as follows: + +.. coqtop:: in reset + + Fixpoint max (n m:nat) {struct m} : nat := + match n, m with + | S n', S m' => S (max n' m') + | 0, p | p, 0 => p + end. + +Similarly, factorization of (not necessarily multiple) patterns that +share the same variables is possible by using the notation :n:`{+| @pattern}`. +Here is an example: + +.. coqtop:: in + + Definition filter_2_4 (n:nat) : nat := + match n with + | 2 as m | 4 as m => m + | _ => 0 + end. + + +Here is another example using disjunctive subpatterns. + +.. coqtop:: in + + Definition filter_some_square_corners (p:nat*nat) : nat*nat := + match p with + | ((2 as m | 4 as m), (3 as n | 5 as n)) => (m,n) + | _ => (0,0) + end. + +About patterns of parametric types +---------------------------------- + +Parameters in patterns +~~~~~~~~~~~~~~~~~~~~~~ + +When matching objects of a parametric type, parameters do not bind in +patterns. They must be substituted by “``_``”. Consider for example the +type of polymorphic lists: + +.. coqtop:: in + + Inductive List (A:Set) : Set := + | nil : List A + | cons : A -> List A -> List A. + +We can check the function *tail*: + +.. coqtop:: all + + Check + (fun l:List nat => + match l with + | nil _ => nil nat + | cons _ _ l' => l' + end). + +When we use parameters in patterns there is an error message: + +.. coqtop:: all + + Fail Check + (fun l:List nat => + match l with + | nil A => nil nat + | cons A _ l' => l' + end). + +.. flag:: Asymmetric Patterns + + This flag (off by default) removes parameters from constructors in patterns: + +.. coqtop:: all + + Set Asymmetric Patterns. + Check (fun l:List nat => + match l with + | nil => nil _ + | cons _ l' => l' + end). + Unset Asymmetric Patterns. + +Implicit arguments in patterns +------------------------------ + +By default, implicit arguments are omitted in patterns. So we write: + +.. coqtop:: all + + Arguments nil {A}. + Arguments cons [A] _ _. + Check + (fun l:List nat => + match l with + | nil => nil + | cons _ l' => l' + end). + +But the possibility to use all the arguments is given by “``@``” implicit +explicitations (as for terms, see :ref:`explicit-applications`). + +.. coqtop:: all + + Check + (fun l:List nat => + match l with + | @nil _ => @nil nat + | @cons _ _ l' => l' + end). + + +.. _matching-dependent: + +Matching objects of dependent types +----------------------------------- + +The previous examples illustrate pattern matching on objects of non- +dependent types, but we can also use the expansion strategy to +destructure objects of dependent types. Consider the type :g:`listn` of +lists of a certain length: + +.. coqtop:: in reset + + Inductive listn : nat -> Set := + | niln : listn 0 + | consn : forall n:nat, nat -> listn n -> listn (S n). + + +Understanding dependencies in patterns +-------------------------------------- + +We can define the function length over :g:`listn` by: + +.. coqdoc:: + + Definition length (n:nat) (l:listn n) := n. + +Just for illustrating pattern matching, we can define it by case +analysis: + +.. coqtop:: in + + Definition length (n:nat) (l:listn n) := + match l with + | niln => 0 + | consn n _ _ => S n + end. + +We can understand the meaning of this definition using the same +notions of usual pattern matching. + + +When the elimination predicate must be provided +----------------------------------------------- + +Dependent pattern matching +~~~~~~~~~~~~~~~~~~~~~~~~~~ + +The examples given so far do not need an explicit elimination +predicate because all the |rhs| have the same type and Coq +succeeds to synthesize it. Unfortunately when dealing with dependent +patterns it often happens that we need to write cases where the types +of the |rhs| are different instances of the elimination predicate. The +function :g:`concat` for :g:`listn` is an example where the branches have +different types and we need to provide the elimination predicate: + +.. coqtop:: in + + Fixpoint concat (n:nat) (l:listn n) (m:nat) (l':listn m) {struct l} : + listn (n + m) := + match l in listn n return listn (n + m) with + | niln => l' + | consn n' a y => consn (n' + m) a (concat n' y m l') + end. + +.. coqtop:: none + + Reset concat. + +The elimination predicate is :g:`fun (n:nat) (l:listn n) => listn (n+m)`. +In general if :g:`m` has type :g:`(I q1 … qr t1 … ts)` where :g:`q1, …, qr` +are parameters, the elimination predicate should be of the form :g:`fun y1 … ys x : (I q1 … qr y1 … ys ) => Q`. + +In the concrete syntax, it should be written : +``match m as x in (I _ … _ y1 … ys) return Q with … end``. +The variables which appear in the ``in`` and ``as`` clause are new and bounded +in the property :g:`Q` in the return clause. The parameters of the +inductive definitions should not be mentioned and are replaced by ``_``. + +Multiple dependent pattern matching +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Recall that a list of patterns is also a pattern. So, when we +destructure several terms at the same time and the branches have +different types we need to provide the elimination predicate for this +multiple pattern. It is done using the same scheme: each term may be +associated to an ``as`` clause and an ``in`` clause in order to introduce +a dependent product. + +For example, an equivalent definition for :g:`concat` (even though the +matching on the second term is trivial) would have been: + +.. coqtop:: in + + Fixpoint concat (n:nat) (l:listn n) (m:nat) (l':listn m) {struct l} : + listn (n + m) := + match l in listn n, l' return listn (n + m) with + | niln, x => x + | consn n' a y, x => consn (n' + m) a (concat n' y m x) + end. + +Even without real matching over the second term, this construction can +be used to keep types linked. If :g:`a` and :g:`b` are two :g:`listn` of the same +length, by writing + +.. coqtop:: in + + Check (fun n (a b: listn n) => + match a, b with + | niln, b0 => tt + | consn n' a y, bS => tt + end). + +we have a copy of :g:`b` in type :g:`listn 0` resp. :g:`listn (S n')`. + +.. _match-in-patterns: + +Patterns in ``in`` +~~~~~~~~~~~~~~~~~~ + +If the type of the matched term is more precise than an inductive +applied to variables, arguments of the inductive in the ``in`` branch can +be more complicated patterns than a variable. + +Moreover, constructors whose types do not follow the same pattern will +become impossible branches. In an impossible branch, you can answer +anything but False_rect unit has the advantage to be subterm of +anything. + +To be concrete: the ``tail`` function can be written: + +.. coqtop:: in + + Definition tail n (v: listn (S n)) := + match v in listn (S m) return listn m with + | niln => False_rect unit + | consn n' a y => y + end. + +and :g:`tail n v` will be subterm of :g:`v`. + +Using pattern matching to write proofs +-------------------------------------- + +In all the previous examples the elimination predicate does not depend +on the object(s) matched. But it may depend and the typical case is +when we write a proof by induction or a function that yields an object +of a dependent type. An example of a proof written using ``match`` is given +in the description of the tactic :tacn:`refine`. + +For example, we can write the function :g:`buildlist` that given a natural +number :g:`n` builds a list of length :g:`n` containing zeros as follows: + +.. coqtop:: in + + Fixpoint buildlist (n:nat) : listn n := + match n return listn n with + | O => niln + | S n => consn n 0 (buildlist n) + end. + +We can also use multiple patterns. Consider the following definition +of the predicate less-equal :g:`Le`: + +.. coqtop:: in + + Inductive LE : nat -> nat -> Prop := + | LEO : forall n:nat, LE 0 n + | LES : forall n m:nat, LE n m -> LE (S n) (S m). + +We can use multiple patterns to write the proof of the lemma +:g:`forall (n m:nat), (LE n m) \/ (LE m n)`: + +.. coqtop:: in + + Fixpoint dec (n m:nat) {struct n} : LE n m \/ LE m n := + match n, m return LE n m \/ LE m n with + | O, x => or_introl (LE x 0) (LEO x) + | x, O => or_intror (LE x 0) (LEO x) + | S n as n', S m as m' => + match dec n m with + | or_introl h => or_introl (LE m' n') (LES n m h) + | or_intror h => or_intror (LE n' m') (LES m n h) + end + end. + +In the example of :g:`dec`, the first match is dependent while the second +is not. + +The user can also use match in combination with the tactic :tacn:`refine` (see +Section 8.2.3) to build incomplete proofs beginning with a match +construction. + + +Pattern-matching on inductive objects involving local definitions +----------------------------------------------------------------- + +If local definitions occur in the type of a constructor, then there +are two ways to match on this constructor. Either the local +definitions are skipped and matching is done only on the true +arguments of the constructors, or the bindings for local definitions +can also be caught in the matching. + +.. example:: + + .. coqtop:: in reset + + Inductive list : nat -> Set := + | nil : list 0 + | cons : forall n:nat, let m := (2 * n) in list m -> list (S (S m)). + + In the next example, the local definition is not caught. + + .. coqtop:: in + + Fixpoint length n (l:list n) {struct l} : nat := + match l with + | nil => 0 + | cons n l0 => S (length (2 * n) l0) + end. + + But in this example, it is. + + .. coqtop:: in + + Fixpoint length' n (l:list n) {struct l} : nat := + match l with + | nil => 0 + | @cons _ m l0 => S (length' m l0) + end. + +.. note:: For a given matching clause, either none of the local + definitions or all of them can be caught. + +.. note:: You can only catch let bindings in mode where you bind all + variables and so you have to use ``@`` syntax. + +.. note:: this feature is incoherent with the fact that parameters + cannot be caught and consequently is somehow hidden. For example, + there is no mention of it in error messages. + +Pattern-matching and coercions +------------------------------ + +If a mismatch occurs between the expected type of a pattern and its +actual type, a coercion made from constructors is sought. If such a +coercion can be found, it is automatically inserted around the +pattern. + +.. example:: + + .. coqtop:: in + + Inductive I : Set := + | C1 : nat -> I + | C2 : I -> I. + + Coercion C1 : nat >-> I. + + .. coqtop:: all + + Check (fun x => match x with + | C2 O => 0 + | _ => 0 + end). + + +When does the expansion strategy fail? +-------------------------------------- + +The strategy works very like in ML languages when treating patterns of +non-dependent types. But there are new cases of failure that are due to +the presence of dependencies. + +The error messages of the current implementation may be sometimes +confusing. When the tactic fails because patterns are somehow +incorrect then error messages refer to the initial expression. But the +strategy may succeed to build an expression whose sub-expressions are +well typed when the whole expression is not. In this situation the +message makes reference to the expanded expression. We encourage +users, when they have patterns with the same outer constructor in +different equations, to name the variable patterns in the same +positions with the same name. E.g. to write ``(cons n O x) => e1`` and +``(cons n _ x) => e2`` instead of ``(cons n O x) => e1`` and +``(cons n' _ x') => e2``. This helps to maintain certain name correspondence between the +generated expression and the original. + +Here is a summary of the error messages corresponding to each +situation: + +.. exn:: The constructor @ident expects @num arguments. + + The variable ident is bound several times in pattern termFound a constructor + of inductive type term while a constructor of term is expectedPatterns are + incorrect (because constructors are not applied to the correct number of the + arguments, because they are not linear or they are wrongly typed). + +.. exn:: Non exhaustive pattern matching. + + The pattern matching is not exhaustive. + +.. exn:: The elimination predicate term should be of arity @num (for non \ + dependent case) or @num (for dependent case). + + The elimination predicate provided to match has not the expected arity. + +.. exn:: Unable to infer a match predicate + Either there is a type incompatibility or the problem involves dependencies. + + There is a type mismatch between the different branches. The user should + provide an elimination predicate. diff --git a/doc/sphinx/addendum/extraction.rst b/doc/sphinx/addendum/extraction.rst new file mode 100644 index 0000000000..e93b01f14d --- /dev/null +++ b/doc/sphinx/addendum/extraction.rst @@ -0,0 +1,630 @@ +.. _extraction: + +Extraction of programs in |OCaml| and Haskell +============================================= + +:Authors: Jean-Christophe Filliâtre and Pierre Letouzey + +We present here the |Coq| extraction commands, used to build certified +and relatively efficient functional programs, extracting them from +either |Coq| functions or |Coq| proofs of specifications. The +functional languages available as output are currently |OCaml|, Haskell +and Scheme. In the following, "ML" will be used (abusively) to refer +to any of the three. + +Before using any of the commands or options described in this chapter, +the extraction framework should first be loaded explicitly +via ``Require Extraction``, or via the more robust +``From Coq Require Extraction``. +Note that in earlier versions of Coq, these commands and options were +directly available without any preliminary ``Require``. + +.. coqtop:: in + + Require Extraction. + +Generating ML Code +------------------- + +.. note:: + + In the following, a qualified identifier :token:`qualid` + can be used to refer to any kind of |Coq| global "object" : constant, + inductive type, inductive constructor or module name. + +The next two commands are meant to be used for rapid preview of +extraction. They both display extracted term(s) inside |Coq|. + +.. cmd:: Extraction @qualid + + Extraction of the mentioned object in the |Coq| toplevel. + +.. cmd:: Recursive Extraction {+ @qualid } + + Recursive extraction of all the mentioned objects and + all their dependencies in the |Coq| toplevel. + +All the following commands produce real ML files. User can choose to +produce one monolithic file or one file per |Coq| library. + +.. cmd:: Extraction @string {+ @qualid } + + Recursive extraction of all the mentioned objects and all + their dependencies in one monolithic file :token:`string`. + Global and local identifiers are renamed according to the chosen ML + language to fulfill its syntactic conventions, keeping original + names as much as possible. + +.. cmd:: Extraction Library @ident + + Extraction of the whole |Coq| library :n:`@ident.v` to an ML module + :n:`@ident.ml`. In case of name clash, identifiers are here renamed + using prefixes ``coq_`` or ``Coq_`` to ensure a session-independent + renaming. + +.. cmd:: Recursive Extraction Library @ident + + Extraction of the |Coq| library :n:`@ident.v` and all other modules + :n:`@ident.v` depends on. + +.. cmd:: Separate Extraction {+ @qualid } + + Recursive extraction of all the mentioned objects and all + their dependencies, just as :n:`Extraction @string {+ @qualid }`, + but instead of producing one monolithic file, this command splits + the produced code in separate ML files, one per corresponding Coq + ``.v`` file. This command is hence quite similar to + :cmd:`Recursive Extraction Library`, except that only the needed + parts of Coq libraries are extracted instead of the whole. + The naming convention in case of name clash is the same one as + :cmd:`Extraction Library`: identifiers are here renamed using prefixes + ``coq_`` or ``Coq_``. + +The following command is meant to help automatic testing of +the extraction, see for instance the ``test-suite`` directory +in the |Coq| sources. + +.. cmd:: Extraction TestCompile {+ @qualid } + + All the mentioned objects and all their dependencies are extracted + to a temporary |OCaml| file, just as in ``Extraction "file"``. Then + this temporary file and its signature are compiled with the same + |OCaml| compiler used to built |Coq|. This command succeeds only + if the extraction and the |OCaml| compilation succeed. It fails + if the current target language of the extraction is not |OCaml|. + +Extraction Options +------------------- + +Setting the target language +~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. cmd:: Extraction Language ( OCaml | Haskell | Scheme ) + :name: Extraction Language + + The ability to fix target language is the first and more important + of the extraction options. Default is ``OCaml``. + + +Inlining and optimizations +~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Since |OCaml| is a strict language, the extracted code has to +be optimized in order to be efficient (for instance, when using +induction principles we do not want to compute all the recursive calls +but only the needed ones). So the extraction mechanism provides an +automatic optimization routine that will be called each time the user +wants to generate an |OCaml| program. The optimizations can be split in two +groups: the type-preserving ones (essentially constant inlining and +reductions) and the non type-preserving ones (some function +abstractions of dummy types are removed when it is deemed safe in order +to have more elegant types). Therefore some constants may not appear in the +resulting monolithic |OCaml| program. In the case of modular extraction, +even if some inlining is done, the inlined constants are nevertheless +printed, to ensure session-independent programs. + +Concerning Haskell, type-preserving optimizations are less useful +because of laziness. We still make some optimizations, for example in +order to produce more readable code. + +The type-preserving optimizations are controlled by the following |Coq| options: + +.. flag:: Extraction Optimize + + Default is on. This controls all type-preserving optimizations made on + the ML terms (mostly reduction of dummy beta/iota redexes, but also + simplifications on Cases, etc). Turn this option off if you want a + ML term as close as possible to the Coq term. + +.. flag:: Extraction Conservative Types + + Default is off. This controls the non type-preserving optimizations + made on ML terms (which try to avoid function abstraction of dummy + types). Turn this option on to make sure that ``e:t`` + implies that ``e':t'`` where ``e'`` and ``t'`` are the extracted + code of ``e`` and ``t`` respectively. + +.. flag:: Extraction KeepSingleton + + Default is off. Normally, when the extraction of an inductive type + produces a singleton type (i.e. a type with only one constructor, and + only one argument to this constructor), the inductive structure is + removed and this type is seen as an alias to the inner type. + The typical example is ``sig``. This option allows disabling this + optimization when one wishes to preserve the inductive structure of types. + +.. flag:: Extraction AutoInline + + Default is on. The extraction mechanism inlines the bodies of + some defined constants, according to some heuristics + like size of bodies, uselessness of some arguments, etc. + Those heuristics are not always perfect; if you want to disable + this feature, turn this option off. + +.. cmd:: Extraction Inline {+ @qualid } + + In addition to the automatic inline feature, the constants + mentioned by this command will always be inlined during extraction. + +.. cmd:: Extraction NoInline {+ @qualid } + + Conversely, the constants mentionned by this command will + never be inlined during extraction. + +.. cmd:: Print Extraction Inline + + Prints the current state of the table recording the custom inlinings + declared by the two previous commands. + +.. cmd:: Reset Extraction Inline + + Empties the table recording the custom inlinings (see the + previous commands). + +**Inlining and printing of a constant declaration:** + +The user can explicitly ask for a constant to be extracted by two means: + + * by mentioning it on the extraction command line + + * by extracting the whole |Coq| module of this constant. + +In both cases, the declaration of this constant will be present in the +produced file. But this same constant may or may not be inlined in +the following terms, depending on the automatic/custom inlining mechanism. + +For the constants non-explicitly required but needed for dependency +reasons, there are two cases: + + * If an inlining decision is taken, whether automatically or not, + all occurrences of this constant are replaced by its extracted body, + and this constant is not declared in the generated file. + + * If no inlining decision is taken, the constant is normally + declared in the produced file. + +Extra elimination of useless arguments +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +The following command provides some extra manual control on the +code elimination performed during extraction, in a way which +is independent but complementary to the main elimination +principles of extraction (logical parts and types). + +.. cmd:: Extraction Implicit @qualid [ {+ @ident } ] + + This experimental command allows declaring some arguments of + :token:`qualid` as implicit, i.e. useless in extracted code and hence to + be removed by extraction. Here :token:`qualid` can be any function or + inductive constructor, and the given :token:`ident` are the names of + the concerned arguments. In fact, an argument can also be referred + by a number indicating its position, starting from 1. + +When an actual extraction takes place, an error is normally raised if the +:cmd:`Extraction Implicit` declarations cannot be honored, that is +if any of the implicit arguments still occurs in the final code. +This behavior can be relaxed via the following option: + +.. flag:: Extraction SafeImplicits + + Default is on. When this option is off, a warning is emitted + instead of an error if some implicit arguments still occur in the + final code of an extraction. This way, the extracted code may be + obtained nonetheless and reviewed manually to locate the source of the issue + (in the code, some comments mark the location of these remaining implicit arguments). + Note that this extracted code might not compile or run properly, + depending of the use of these remaining implicit arguments. + +Realizing axioms +~~~~~~~~~~~~~~~~ + +Extraction will fail if it encounters an informative axiom not realized. +A warning will be issued if it encounters a logical axiom, to remind the +user that inconsistent logical axioms may lead to incorrect or +non-terminating extracted terms. + +It is possible to assume some axioms while developing a proof. Since +these axioms can be any kind of proposition or object or type, they may +perfectly well have some computational content. But a program must be +a closed term, and of course the system cannot guess the program which +realizes an axiom. Therefore, it is possible to tell the system +what ML term corresponds to a given axiom. + +.. cmd:: Extract Constant @qualid => @string + + Give an ML extraction for the given constant. + The :token:`string` may be an identifier or a quoted string. + +.. cmd:: Extract Inlined Constant @qualid => @string + + Same as the previous one, except that the given ML terms will + be inlined everywhere instead of being declared via a ``let``. + + .. note:: + This command is sugar for an :cmd:`Extract Constant` followed + by a :cmd:`Extraction Inline`. Hence a :cmd:`Reset Extraction Inline` + will have an effect on the realized and inlined axiom. + +.. caution:: It is the responsibility of the user to ensure that the ML + terms given to realize the axioms do have the expected types. In + fact, the strings containing realizing code are just copied to the + extracted files. The extraction recognizes whether the realized axiom + should become a ML type constant or a ML object declaration. For example: + +.. coqtop:: in + + Axiom X:Set. + Axiom x:X. + Extract Constant X => "int". + Extract Constant x => "0". + +Notice that in the case of type scheme axiom (i.e. whose type is an +arity, that is a sequence of product finished by a sort), then some type +variables have to be given (as quoted strings). The syntax is then: + +.. cmdv:: Extract Constant @qualid @string ... @string => @string + :undocumented: + +The number of type variables is checked by the system. For example: + +.. coqtop:: in + + Axiom Y : Set -> Set -> Set. + Extract Constant Y "'a" "'b" => " 'a * 'b ". + +Realizing an axiom via :cmd:`Extract Constant` is only useful in the +case of an informative axiom (of sort ``Type`` or ``Set``). A logical axiom +has no computational content and hence will not appear in extracted +terms. But a warning is nonetheless issued if extraction encounters a +logical axiom. This warning reminds user that inconsistent logical +axioms may lead to incorrect or non-terminating extracted terms. + +If an informative axiom has not been realized before an extraction, a +warning is also issued and the definition of the axiom is filled with +an exception labeled ``AXIOM TO BE REALIZED``. The user must then +search these exceptions inside the extracted file and replace them by +real code. + +Realizing inductive types +~~~~~~~~~~~~~~~~~~~~~~~~~ + +The system also provides a mechanism to specify ML terms for inductive +types and constructors. For instance, the user may want to use the ML +native boolean type instead of the |Coq| one. The syntax is the following: + +.. cmd:: Extract Inductive @qualid => @string [ {+ @string } ] + + Give an ML extraction for the given inductive type. You must specify + extractions for the type itself (first :token:`string`) and all its + constructors (all the :token:`string` between square brackets). In this form, + the ML extraction must be an ML inductive datatype, and the native + pattern matching of the language will be used. + +.. cmdv:: Extract Inductive @qualid => @string [ {+ @string } ] @string + + Same as before, with a final extra :token:`string` that indicates how to + perform pattern matching over this inductive type. In this form, + the ML extraction could be an arbitrary type. + For an inductive type with :math:`k` constructors, the function used to + emulate the pattern matching should expect :math:`k+1` arguments, first the :math:`k` + branches in functional form, and then the inductive element to + destruct. For instance, the match branch ``| S n => foo`` gives the + functional form ``(fun n -> foo)``. Note that a constructor with no + arguments is considered to have one unit argument, in order to block + early evaluation of the branch: ``| O => bar`` leads to the functional + form ``(fun () -> bar)``. For instance, when extracting :g:`nat` + into |OCaml| ``int``, the code to be provided has type: + ``(unit->'a)->(int->'a)->int->'a``. + +.. caution:: As for :cmd:`Extract Constant`, this command should be used with care: + + * The ML code provided by the user is currently **not** checked at all by + extraction, even for syntax errors. + + * Extracting an inductive type to a pre-existing ML inductive type + is quite sound. But extracting to a general type (by providing an + ad-hoc pattern matching) will often **not** be fully rigorously + correct. For instance, when extracting ``nat`` to |OCaml| ``int``, + it is theoretically possible to build ``nat`` values that are + larger than |OCaml| ``max_int``. It is the user's responsibility to + be sure that no overflow or other bad events occur in practice. + + * Translating an inductive type to an arbitrary ML type does **not** + magically improve the asymptotic complexity of functions, even if the + ML type is an efficient representation. For instance, when extracting + ``nat`` to |OCaml| ``int``, the function ``Nat.mul`` stays quadratic. + It might be interesting to associate this translation with + some specific :cmd:`Extract Constant` when primitive counterparts exist. + +Typical examples are the following: + +.. coqtop:: in + + Extract Inductive unit => "unit" [ "()" ]. + Extract Inductive bool => "bool" [ "true" "false" ]. + Extract Inductive sumbool => "bool" [ "true" "false" ]. + +.. note:: + + When extracting to |OCaml|, if an inductive constructor or type has arity 2 and + the corresponding string is enclosed by parentheses, and the string meets + |OCaml|'s lexical criteria for an infix symbol, then the rest of the string is + used as an infix constructor or type. + +.. coqtop:: in + + Extract Inductive list => "list" [ "[]" "(::)" ]. + Extract Inductive prod => "(*)" [ "(,)" ]. + +As an example of translation to a non-inductive datatype, let's turn +``nat`` into |OCaml| ``int`` (see caveat above): + +.. coqtop:: in + + Extract Inductive nat => int [ "0" "succ" ] "(fun fO fS n -> if n=0 then fO () else fS (n-1))". + +Avoiding conflicts with existing filenames +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +When using :cmd:`Extraction Library`, the names of the extracted files +directly depend on the names of the |Coq| files. It may happen that +these filenames are in conflict with already existing files, +either in the standard library of the target language or in other +code that is meant to be linked with the extracted code. +For instance the module ``List`` exists both in |Coq| and in |OCaml|. +It is possible to instruct the extraction not to use particular filenames. + +.. cmd:: Extraction Blacklist {+ @ident } + + Instruct the extraction to avoid using these names as filenames + for extracted code. + +.. cmd:: Print Extraction Blacklist + + Show the current list of filenames the extraction should avoid. + +.. cmd:: Reset Extraction Blacklist + + Allow the extraction to use any filename. + +For |OCaml|, a typical use of these commands is +``Extraction Blacklist String List``. + +Additional settings +~~~~~~~~~~~~~~~~~~~ + +.. opt:: Extraction File Comment @string + :name: Extraction File Comment + + Provides a comment that is included at the beginning of the output files. + +.. opt:: Extraction Flag @num + :name: Extraction Flag + + Controls which optimizations are used during extraction, providing a finer-grained + control than :flag:`Extraction Optimize`. The bits of :token:`num` are used as a bit mask. + Keeping an option off keeps the extracted ML more similar to the Coq term. + Values are: + + +-----+-------+----------------------------------------------------------------+ + | Bit | Value | Optimization (default is on unless noted otherwise) | + +-----+-------+----------------------------------------------------------------+ + | 0 | 1 | Remove local dummy variables | + +-----+-------+----------------------------------------------------------------+ + | 1 | 2 | Use special treatment for fixpoints | + +-----+-------+----------------------------------------------------------------+ + | 2 | 4 | Simplify case with iota-redux | + +-----+-------+----------------------------------------------------------------+ + | 3 | 8 | Factor case branches as functions | + +-----+-------+----------------------------------------------------------------+ + | 4 | 16 | (not available, default false) | + +-----+-------+----------------------------------------------------------------+ + | 5 | 32 | Simplify case as function of one argument | + +-----+-------+----------------------------------------------------------------+ + | 6 | 64 | Simplify case by swapping case and lambda | + +-----+-------+----------------------------------------------------------------+ + | 7 | 128 | Some case optimization | + +-----+-------+----------------------------------------------------------------+ + | 8 | 256 | Push arguments inside a letin | + +-----+-------+----------------------------------------------------------------+ + | 9 | 512 | Use linear let reduction (default false) | + +-----+-------+----------------------------------------------------------------+ + | 10 | 1024 | Use linear beta reduction (default false) | + +-----+-------+----------------------------------------------------------------+ + +.. flag:: Extraction TypeExpand + + If set, fully expand Coq types in ML. See the Coq source code to learn more. + +Differences between |Coq| and ML type systems +---------------------------------------------- + +Due to differences between |Coq| and ML type systems, +some extracted programs are not directly typable in ML. +We now solve this problem (at least in |OCaml|) by adding +when needed some unsafe casting ``Obj.magic``, which give +a generic type ``'a`` to any term. + +First, if some part of the program is *very* polymorphic, there +may be no ML type for it. In that case the extraction to ML works +alright but the generated code may be refused by the ML +type checker. A very well known example is the ``distr-pair`` +function: + +.. coqtop:: in + + Definition dp {A B:Type}(x:A)(y:B)(f:forall C:Type, C->C) := (f A x, f B y). + +In |OCaml|, for instance, the direct extracted term would be:: + + let dp x y f = Pair((f () x),(f () y)) + +and would have type:: + + dp : 'a -> 'a -> (unit -> 'a -> 'b) -> ('b,'b) prod + +which is not its original type, but a restriction. + +We now produce the following correct version:: + + let dp x y f = Pair ((Obj.magic f () x), (Obj.magic f () y)) + +Secondly, some |Coq| definitions may have no counterpart in ML. This +happens when there is a quantification over types inside the type +of a constructor; for example: + +.. coqtop:: in + + Inductive anything : Type := dummy : forall A:Set, A -> anything. + +which corresponds to the definition of an ML dynamic type. +In |OCaml|, we must cast any argument of the constructor dummy +(no GADT are produced yet by the extraction). + +Even with those unsafe castings, you should never get error like +``segmentation fault``. In fact even if your program may seem +ill-typed to the |OCaml| type checker, it can't go wrong : it comes +from a Coq well-typed terms, so for example inductive types will always +have the correct number of arguments, etc. Of course, when launching +manually some extracted function, you should apply it to arguments +of the right shape (from the |Coq| point-of-view). + +More details about the correctness of the extracted programs can be +found in :cite:`Let02`. + +We have to say, though, that in most "realistic" programs, these problems do not +occur. For example all the programs of Coq library are accepted by the |OCaml| +type checker without any ``Obj.magic`` (see examples below). + +Some examples +------------- + +We present here two examples of extraction, taken from the +|Coq| Standard Library. We choose |OCaml| as the target language, +but everything, with slight modifications, can also be done in the +other languages supported by extraction. +We then indicate where to find other examples and tests of extraction. + +A detailed example: Euclidean division +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +The file ``Euclid`` contains the proof of Euclidean division. +The natural numbers used here are unary, represented by the type``nat``, +which is defined by two constructors ``O`` and ``S``. +This module contains a theorem ``eucl_dev``, whose type is:: + + forall b:nat, b > 0 -> forall a:nat, diveucl a b + +where ``diveucl`` is a type for the pair of the quotient and the +modulo, plus some logical assertions that disappear during extraction. +We can now extract this program to |OCaml|: + +.. coqtop:: none + + Reset Initial. + +.. coqtop:: all + + Require Extraction. + Require Import Euclid Wf_nat. + Extraction Inline gt_wf_rec lt_wf_rec induction_ltof2. + Recursive Extraction eucl_dev. + +The inlining of ``gt_wf_rec`` and others is not +mandatory. It only enhances readability of extracted code. +You can then copy-paste the output to a file ``euclid.ml`` or let +|Coq| do it for you with the following command:: + + Extraction "euclid" eucl_dev. + +Let us play the resulting program (in an |OCaml| toplevel):: + + #use "euclid.ml";; + type nat = O | S of nat + type sumbool = Left | Right + val sub : nat -> nat -> nat = <fun> + val le_lt_dec : nat -> nat -> sumbool = <fun> + val le_gt_dec : nat -> nat -> sumbool = <fun> + type diveucl = Divex of nat * nat + val eucl_dev : nat -> nat -> diveucl = <fun> + + # eucl_dev (S (S O)) (S (S (S (S (S O)))));; + - : diveucl = Divex (S (S O), S O) + +It is easier to test on |OCaml| integers:: + + # let rec nat_of_int = function 0 -> O | n -> S (nat_of_int (n-1));; + val nat_of_int : int -> nat = <fun> + + # let rec int_of_nat = function O -> 0 | S p -> 1+(int_of_nat p);; + val int_of_nat : nat -> int = <fun> + + # let div a b = + let Divex (q,r) = eucl_dev (nat_of_int b) (nat_of_int a) + in (int_of_nat q, int_of_nat r);; + val div : int -> int -> int * int = <fun> + + # div 173 15;; + - : int * int = (11, 8) + +Note that these ``nat_of_int`` and ``int_of_nat`` are now +available via a mere ``Require Import ExtrOcamlIntConv`` and then +adding these functions to the list of functions to extract. This file +``ExtrOcamlIntConv.v`` and some others in ``plugins/extraction/`` +are meant to help building concrete program via extraction. + +Extraction's horror museum +~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Some pathological examples of extraction are grouped in the file +``test-suite/success/extraction.v`` of the sources of |Coq|. + +Users' Contributions +~~~~~~~~~~~~~~~~~~~~ + +Several of the |Coq| Users' Contributions use extraction to produce +certified programs. In particular the following ones have an automatic +extraction test: + + * ``additions`` : https://github.com/coq-contribs/additions + * ``bdds`` : https://github.com/coq-contribs/bdds + * ``canon-bdds`` : https://github.com/coq-contribs/canon-bdds + * ``chinese`` : https://github.com/coq-contribs/chinese + * ``continuations`` : https://github.com/coq-contribs/continuations + * ``coq-in-coq`` : https://github.com/coq-contribs/coq-in-coq + * ``exceptions`` : https://github.com/coq-contribs/exceptions + * ``firing-squad`` : https://github.com/coq-contribs/firing-squad + * ``founify`` : https://github.com/coq-contribs/founify + * ``graphs`` : https://github.com/coq-contribs/graphs + * ``higman-cf`` : https://github.com/coq-contribs/higman-cf + * ``higman-nw`` : https://github.com/coq-contribs/higman-nw + * ``hardware`` : https://github.com/coq-contribs/hardware + * ``multiplier`` : https://github.com/coq-contribs/multiplier + * ``search-trees`` : https://github.com/coq-contribs/search-trees + * ``stalmarck`` : https://github.com/coq-contribs/stalmarck + +Note that ``continuations`` and ``multiplier`` are a bit particular. They are +examples of developments where ``Obj.magic`` is needed. This is +probably due to a heavy use of impredicativity. After compilation, those +two examples run nonetheless, thanks to the correction of the +extraction :cite:`Let02`. diff --git a/doc/sphinx/addendum/generalized-rewriting.rst b/doc/sphinx/addendum/generalized-rewriting.rst new file mode 100644 index 0000000000..b474c51f17 --- /dev/null +++ b/doc/sphinx/addendum/generalized-rewriting.rst @@ -0,0 +1,833 @@ +.. _generalizedrewriting: + +Generalized rewriting +===================== + +:Author: Matthieu Sozeau + +This chapter presents the extension of several equality related +tactics to work over user-defined structures (called setoids) that are +equipped with ad-hoc equivalence relations meant to behave as +equalities. Actually, the tactics have also been generalized to +relations weaker then equivalences (e.g. rewriting systems). The +toolbox also extends the automatic rewriting capabilities of the +system, allowing the specification of custom strategies for rewriting. + +This documentation is adapted from the previous setoid documentation +by Claudio Sacerdoti Coen (based on previous work by Clément Renard). +The new implementation is a drop-in replacement for the old one +[#tabareau]_, hence most of the documentation still applies. + +The work is a complete rewrite of the previous implementation, based +on the typeclass infrastructure. It also improves on and generalizes +the previous implementation in several ways: + ++ User-extensible algorithm. The algorithm is separated into two parts: + generation of the rewriting constraints (written in ML) and solving + these constraints using typeclass resolution. As typeclass + resolution is extensible using tactics, this allows users to define + general ways to solve morphism constraints. ++ Subrelations. An example extension to the base algorithm is the + ability to define one relation as a subrelation of another so that + morphism declarations on one relation can be used automatically for + the other. This is done purely using tactics and typeclass search. ++ Rewriting under binders. It is possible to rewrite under binders in + the new implementation, if one provides the proper morphisms. Again, + most of the work is handled in the tactics. ++ First-class morphisms and signatures. Signatures and morphisms are + ordinary Coq terms, hence they can be manipulated inside Coq, put + inside structures and lemmas about them can be proved inside the + system. Higher-order morphisms are also allowed. ++ Performance. The implementation is based on a depth-first search for + the first solution to a set of constraints which can be as fast as + linear in the size of the term, and the size of the proof term is + linear in the size of the original term. Besides, the extensibility + allows the user to customize the proof search if necessary. + +.. [#tabareau] Nicolas Tabareau helped with the gluing. + +Introduction to generalized rewriting +------------------------------------- + + +Relations and morphisms +~~~~~~~~~~~~~~~~~~~~~~~ + +A parametric *relation* ``R`` is any term of type +``forall (x1 : T1) ... (xn : Tn), relation A``. +The expression ``A``, which depends on ``x1 ... xn`` , is called the *carrier* +of the relation and ``R`` is said to be a relation over ``A``; the list +``x1,...,xn`` is the (possibly empty) list of parameters of the relation. + +.. example:: Parametric relation + + It is possible to implement finite sets of elements of type ``A`` as + unordered lists of elements of type ``A``. + The function ``set_eq: forall (A : Type), relation (list A)`` + satisfied by two lists with the same elements is a parametric relation + over ``(list A)`` with one parameter ``A``. The type of ``set_eq`` + is convertible with ``forall (A : Type), list A -> list A -> Prop.`` + +An *instance* of a parametric relation ``R`` with n parameters is any term +``(R t1 ... tn)``. + +Let ``R`` be a relation over ``A`` with ``n`` parameters. A term is a parametric +proof of reflexivity for ``R`` if it has type +``forall (x1 : T1) ... (xn : Tn), reflexive (R x1 ... xn)``. +Similar definitions are given for parametric proofs of symmetry and transitivity. + +.. example:: Parametric relation (continued) + + The ``set_eq`` relation of the previous example can be proved to be + reflexive, symmetric and transitive. A parametric unary function ``f`` of type + ``forall (x1 : T1) ... (xn : Tn), A1 -> A2`` covariantly respects two parametric relation instances + ``R1`` and ``R2`` if, whenever ``x``, ``y`` satisfy ``R1 x y``, their images (``f x``) and (``f y``) + satisfy ``R2 (f x) (f y)``. An ``f`` that respects its input and output + relations will be called a unary covariant *morphism*. We can also say + that ``f`` is a monotone function with respect to ``R1`` and ``R2`` . The + sequence ``x1 ... xn`` represents the parameters of the morphism. + +Let ``R1`` and ``R2`` be two parametric relations. The *signature* of a +parametric morphism of type ``forall (x1 : T1) ... (xn : Tn), A1 -> A2`` +that covariantly respects two instances :math:`I_{R_1}` and :math:`I_{R_2}` of ``R1`` and ``R2`` +is written :math:`I_{R_1} ++> I_{R_2}`. Notice that the special arrow ++>, which +reminds the reader of covariance, is placed between the two relation +instances, not between the two carriers. The signature relation +instances and morphism will be typed in a context introducing +variables for the parameters. + +The previous definitions are extended straightforwardly to n-ary +morphisms, that are required to be simultaneously monotone on every +argument. + +Morphisms can also be contravariant in one or more of their arguments. +A morphism is contravariant on an argument associated to the relation +instance :math:`R` if it is covariant on the same argument when the inverse +relation :math:`R^{−1}` (``inverse R`` in Coq) is considered. The special arrow ``-->`` +is used in signatures for contravariant morphisms. + +Functions having arguments related by symmetric relations instances +are both covariant and contravariant in those arguments. The special +arrow ``==>`` is used in signatures for morphisms that are both +covariant and contravariant. + +An instance of a parametric morphism :math:`f` with :math:`n` +parameters is any term :math:`f \, t_1 \ldots t_n`. + +.. example:: Morphisms + + Continuing the previous example, let ``union: forall (A : Type), list A -> list A -> list A`` + perform the union of two sets by appending one list to the other. ``union` is a binary + morphism parametric over ``A`` that respects the relation instance + ``(set_eq A)``. The latter condition is proved by showing: + + .. coqdoc:: + + forall (A: Type) (S1 S1' S2 S2': list A), + set_eq A S1 S1' -> + set_eq A S2 S2' -> + set_eq A (union A S1 S2) (union A S1' S2'). + + The signature of the function ``union A`` is ``set_eq A ==> set_eq A ==> set_eq A`` + for all ``A``. + +.. example:: Contravariant morphisms + + The division function ``Rdiv : R -> R -> R`` is a morphism of signature + ``le ++> le --> le`` where ``le`` is the usual order relation over + real numbers. Notice that division is covariant in its first argument + and contravariant in its second argument. + +Leibniz equality is a relation and every function is a morphism that +respects Leibniz equality. Unfortunately, Leibniz equality is not +always the intended equality for a given structure. + +In the next section we will describe the commands to register terms as +parametric relations and morphisms. Several tactics that deal with +equality in Coq can also work with the registered relations. The exact +list of tactics will be given :ref:`in this section <tactics-enabled-on-user-provided-relations>`. +For instance, the tactic reflexivity can be used to solve a goal ``R n n`` whenever ``R`` +is an instance of a registered reflexive relation. However, the +tactics that replace in a context ``C[]`` one term with another one +related by ``R`` must verify that ``C[]`` is a morphism that respects the +intended relation. Currently the verification consists of checking +whether ``C[]`` is a syntactic composition of morphism instances that respects some obvious +compatibility constraints. + +.. example:: Rewriting + + Continuing the previous examples, suppose that the user must prove + ``set_eq int (union int (union int S1 S2) S2) (f S1 S2)`` under the + hypothesis ``H : set_eq int S2 (@nil int)``. It + is possible to use the ``rewrite`` tactic to replace the first two + occurrences of ``S2`` with ``@nil int`` in the goal since the + context ``set_eq int (union int (union int S1 nil) nil) (f S1 S2)``, + being a composition of morphisms instances, is a morphism. However the + tactic will fail replacing the third occurrence of ``S2`` unless ``f`` + has also been declared as a morphism. + + +Adding new relations and morphisms +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. cmd:: Add Parametric Relation (x1 : T1) ... (xn : Tk) : (A t1 ... tn) (Aeq t′1 ... t′m) {? reflexivity proved by refl} {? symmetry proved by sym} {? transitivity proved by trans} as @ident + + This command declares a parametric relation :g:`Aeq: forall (y1 : β1 ... ym : βm)`, + :g:`relation (A t1 ... tn)` over :g:`(A : αi -> ... αn -> Type)`. + + The :token:`ident` gives a unique name to the morphism and it is used + by the command to generate fresh names for automatically provided + lemmas used internally. + + Notice that the carrier and relation parameters may refer to the + context of variables introduced at the beginning of the declaration, + but the instances need not be made only of variables. Also notice that + ``A`` is *not* required to be a term having the same parameters as ``Aeq``, + although that is often the case in practice (this departs from the + previous implementation). + + To use this command, you need to first import the module ``Setoid`` using + the command ``Require Import Setoid``. + +.. cmd:: Add Relation + + In case the carrier and relations are not parametric, one can use this command + instead, whose syntax is the same except there is no local context. + + The proofs of reflexivity, symmetry and transitivity can be omitted if + the relation is not an equivalence relation. The proofs must be + instances of the corresponding relation definitions: e.g. the proof of + reflexivity must have a type convertible to + :g:`reflexive (A t1 ... tn) (Aeq t′ 1 …t′ n)`. + Each proof may refer to the introduced variables as well. + +.. example:: Parametric relation + + For Leibniz equality, we may declare: + + .. coqdoc:: + + Add Parametric Relation (A : Type) : A (@eq A) + [reflexivity proved by @refl_equal A] + ... + +Some tactics (:tacn:`reflexivity`, :tacn:`symmetry`, :tacn:`transitivity`) work only on +relations that respect the expected properties. The remaining tactics +(:tacn:`replace`, :tacn:`rewrite` and derived tactics such as :tacn:`autorewrite`) do not +require any properties over the relation. However, they are able to +replace terms with related ones only in contexts that are syntactic +compositions of parametric morphism instances declared with the +following command. + +.. cmd:: Add Parametric Morphism (x1 : T1) ... (xk : Tk) : (f t1 ... tn) with signature sig as @ident + + This command declares ``f`` as a parametric morphism of signature ``sig``. The + identifier :token:`ident` gives a unique name to the morphism and it is used as + the base name of the typeclass instance definition and as the name of + the lemma that proves the well-definedness of the morphism. The + parameters of the morphism as well as the signature may refer to the + context of variables. The command asks the user to prove interactively + that ``f`` respects the relations identified from the signature. + +.. example:: + + We start the example by assuming a small theory over + homogeneous sets and we declare set equality as a parametric + equivalence relation and union of two sets as a parametric morphism. + + .. coqtop:: in + + Require Export Setoid. + Require Export Relation_Definitions. + + Set Implicit Arguments. + + Parameter set : Type -> Type. + Parameter empty : forall A, set A. + Parameter eq_set : forall A, set A -> set A -> Prop. + Parameter union : forall A, set A -> set A -> set A. + + Axiom eq_set_refl : forall A, reflexive _ (eq_set (A:=A)). + Axiom eq_set_sym : forall A, symmetric _ (eq_set (A:=A)). + Axiom eq_set_trans : forall A, transitive _ (eq_set (A:=A)). + Axiom empty_neutral : forall A (S : set A), eq_set (union S (empty A)) S. + + Axiom union_compat : + forall (A : Type), + forall x x' : set A, eq_set x x' -> + forall y y' : set A, eq_set y y' -> + eq_set (union x y) (union x' y'). + + Add Parametric Relation A : (set A) (@eq_set A) + reflexivity proved by (eq_set_refl (A:=A)) + symmetry proved by (eq_set_sym (A:=A)) + transitivity proved by (eq_set_trans (A:=A)) + as eq_set_rel. + + Add Parametric Morphism A : (@union A) + with signature (@eq_set A) ==> (@eq_set A) ==> (@eq_set A) as union_mor. + Proof. + exact (@union_compat A). + Qed. + + It is possible to reduce the burden of specifying parameters using + (maximally inserted) implicit arguments. If ``A`` is always set as + maximally implicit in the previous example, one can write: + + .. coqdoc:: + + Add Parametric Relation A : (set A) eq_set + reflexivity proved by eq_set_refl + symmetry proved by eq_set_sym + transitivity proved by eq_set_trans + as eq_set_rel. + + Add Parametric Morphism A : (@union A) with + signature eq_set ==> eq_set ==> eq_set as union_mor. + Proof. exact (@union_compat A). Qed. + + We proceed now by proving a simple lemma performing a rewrite step and + then applying reflexivity, as we would do working with Leibniz + equality. Both tactic applications are accepted since the required + properties over ``eq_set`` and ``union`` can be established from the two + declarations above. + + .. coqtop:: in + + Goal forall (S : set nat), + eq_set (union (union S (empty nat)) S) (union S S). + + .. coqtop:: in + + Proof. intros. rewrite empty_neutral. reflexivity. Qed. + + The tables of relations and morphisms are managed by the typeclass + instance mechanism. The behavior on section close is to generalize the + instances by the variables of the section (and possibly hypotheses + used in the proofs of instance declarations) but not to export them in + the rest of the development for proof search. One can use the + cmd:`Existing Instance` command to do so outside the section, using the name of the + declared morphism suffixed by ``_Morphism``, or use the ``Global`` modifier + for the corresponding class instance declaration + (see :ref:`First Class Setoids and Morphisms <first-class-setoids-and-morphisms>`) at + definition time. When loading a compiled file or importing a module, + all the declarations of this module will be loaded. + + +Rewriting and non reflexive relations +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +To replace only one argument of an n-ary morphism it is necessary to +prove that all the other arguments are related to themselves by the +respective relation instances. + +.. example:: + + To replace ``(union S empty)`` with ``S`` in ``(union (union S empty) S) (union S S)`` + the rewrite tactic must exploit the monotony of ``union`` (axiom ``union_compat`` + in the previous example). Applying ``union_compat`` by hand we are left with the + goal ``eq_set (union S S) (union S S)``. + +When the relations associated to some arguments are not reflexive, the +tactic cannot automatically prove the reflexivity goals, that are left +to the user. + +Setoids whose relations are partial equivalence relations (PER) are +useful for dealing with partial functions. Let ``R`` be a PER. We say that an +element ``x`` is defined if ``R x x``. A partial function whose domain +comprises all the defined elements is declared as a morphism that +respects ``R``. Every time a rewriting step is performed the user must +prove that the argument of the morphism is defined. + +.. example:: + + Let ``eqO`` be ``fun x y => x = y /\ x <> 0`` (the + smallest PER over nonzero elements). Division can be declared as a + morphism of signature ``eq ==> eq0 ==> eq``. Replacing ``x`` with + ``y`` in ``div x n = div y n`` opens an additional goal ``eq0 n n`` + which is equivalent to ``n = n /\ n <> 0``. + + +Rewriting and non symmetric relations +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +When the user works up to relations that are not symmetric, it is no +longer the case that any covariant morphism argument is also +contravariant. As a result it is no longer possible to replace a term +with a related one in every context, since the obtained goal implies +the previous one if and only if the replacement has been performed in +a contravariant position. In a similar way, replacement in an +hypothesis can be performed only if the replaced term occurs in a +covariant position. + +.. example:: Covariance and contravariance + + Suppose that division over real numbers has been defined as a morphism of signature + ``Z.div : Z.lt ++> Z.lt --> Z.lt`` (i.e. ``Z.div`` is increasing in + its first argument, but decreasing on the second one). Let ``<`` + denote ``Z.lt``. Under the hypothesis ``H : x < y`` we have + ``k < x / y -> k < x / x``, but not ``k < y / x -> k < x / x``. Dually, + under the same hypothesis ``k < x / y -> k < y / y`` holds, but + ``k < y / x -> k < y / y`` does not. Thus, if the current goal is + ``k < x / x``, it is possible to replace only the second occurrence of + ``x`` (in contravariant position) with ``y`` since the obtained goal + must imply the current one. On the contrary, if ``k < x / x`` is an + hypothesis, it is possible to replace only the first occurrence of + ``x`` (in covariant position) with ``y`` since the current + hypothesis must imply the obtained one. + + Contrary to the previous implementation, no specific error message + will be raised when trying to replace a term that occurs in the wrong + position. It will only fail because the rewriting constraints are not + satisfiable. However it is possible to use the at modifier to specify + which occurrences should be rewritten. + + As expected, composing morphisms together propagates the variance + annotations by switching the variance every time a contravariant + position is traversed. + +.. example:: + + Let us continue the previous example and let us consider + the goal ``x / (x / x) < k``. The first and third occurrences of + ``x`` are in a contravariant position, while the second one is in + covariant position. More in detail, the second occurrence of ``x`` + occurs covariantly in ``(x / x)`` (since division is covariant in + its first argument), and thus contravariantly in ``x / (x / x)`` + (since division is contravariant in its second argument), and finally + covariantly in ``x / (x / x) < k`` (since ``<``, as every + transitive relation, is contravariant in its first argument with + respect to the relation itself). + + +Rewriting in ambiguous setoid contexts +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +One function can respect several different relations and thus it can +be declared as a morphism having multiple signatures. + +.. example:: + + Union over homogeneous lists can be given all the + following signatures: ``eq ==> eq ==> eq`` (``eq`` being the + equality over ordered lists) ``set_eq ==> set_eq ==> set_eq`` + (``set_eq`` being the equality over unordered lists up to duplicates), + ``multiset_eq ==> multiset_eq ==> multiset_eq`` (``multiset_eq`` + being the equality over unordered lists). + +To declare multiple signatures for a morphism, repeat the :cmd:`Add Morphism` +command. + +When morphisms have multiple signatures it can be the case that a +rewrite request is ambiguous, since it is unclear what relations +should be used to perform the rewriting. Contrary to the previous +implementation, the tactic will always choose the first possible +solution to the set of constraints generated by a rewrite and will not +try to find *all* the possible solutions to warn the user about them. + + +Commands and tactics +-------------------- + + +.. _first-class-setoids-and-morphisms: + +First class setoids and morphisms +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + + + +The implementation is based on a first-class representation of +properties of relations and morphisms as typeclasses. That is, the +various combinations of properties on relations and morphisms are +represented as records and instances of theses classes are put in a +hint database. For example, the declaration: + +.. coqdoc:: + + Add Parametric Relation (x1 : T1) ... (xn : Tn) : (A t1 ... tn) (Aeq t′1 ... t′m) + [reflexivity proved by refl] + [symmetry proved by sym] + [transitivity proved by trans] + as id. + + +is equivalent to an instance declaration: + +.. coqdoc:: + + Instance (x1 : T1) ... (xn : Tn) => id : @Equivalence (A t1 ... tn) (Aeq t′1 ... t′m) := + [Equivalence_Reflexive := refl] + [Equivalence_Symmetric := sym] + [Equivalence_Transitive := trans]. + +The declaration itself amounts to the definition of an object of the +record type ``Coq.Classes.RelationClasses.Equivalence`` and a hint added +to the ``typeclass_instances`` hint database. Morphism declarations are +also instances of a typeclass defined in ``Classes.Morphisms``. See the +documentation on :ref:`typeclasses` and the theories files in Classes +for further explanations. + +One can inform the rewrite tactic about morphisms and relations just +by using the typeclass mechanism to declare them using Instance and +Context vernacular commands. Any object of type Proper (the type of +morphism declarations) in the local context will also be automatically +used by the rewriting tactic to solve constraints. + +Other representations of first class setoids and morphisms can also be +handled by encoding them as records. In the following example, the +projections of the setoid relation and of the morphism function can be +registered as parametric relations and morphisms. + +.. example:: First class setoids + + .. coqtop:: in reset + + Require Import Relation_Definitions Setoid. + + Record Setoid : Type := + { car: Type; + eq: car -> car -> Prop; + refl: reflexive _ eq; + sym: symmetric _ eq; + trans: transitive _ eq + }. + + Add Parametric Relation (s : Setoid) : (@car s) (@eq s) + reflexivity proved by (refl s) + symmetry proved by (sym s) + transitivity proved by (trans s) as eq_rel. + + Record Morphism (S1 S2 : Setoid) : Type := + { f: car S1 -> car S2; + compat: forall (x1 x2 : car S1), eq S1 x1 x2 -> eq S2 (f x1) (f x2) + }. + + Add Parametric Morphism (S1 S2 : Setoid) (M : Morphism S1 S2) : + (@f S1 S2 M) with signature (@eq S1 ==> @eq S2) as apply_mor. + Proof. apply (compat S1 S2 M). Qed. + + Lemma test : forall (S1 S2 : Setoid) (m : Morphism S1 S2) + (x y : car S1), eq S1 x y -> eq S2 (f _ _ m x) (f _ _ m y). + Proof. intros. rewrite H. reflexivity. Qed. + +.. _tactics-enabled-on-user-provided-relations: + +Tactics enabled on user provided relations +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +The following tactics, all prefixed by ``setoid_``, deal with arbitrary +registered relations and morphisms. Moreover, all the corresponding +unprefixed tactics (i.e. :tacn:`reflexivity`, :tacn:`symmetry`, :tacn:`transitivity`, +:tacn:`replace`, :tacn:`rewrite`) have been extended to fall back to their prefixed +counterparts when the relation involved is not Leibniz equality. +Notice, however, that using the prefixed tactics it is possible to +pass additional arguments such as ``using relation``. + +.. tacv:: setoid_reflexivity + setoid_symmetry {? in @ident} + setoid_transitivity + setoid_rewrite {? @orientation} @term {? at @occs} {? in @ident} + setoid_replace @term with @term {? using relation @term} {? in @ident} {? by @tactic} + :name: setoid_reflexivity; setoid_symmetry; setoid_transitivity; setoid_rewrite; setoid_replace + + The ``using relation`` arguments cannot be passed to the unprefixed form. + The latter argument tells the tactic what parametric relation should + be used to replace the first tactic argument with the second one. If + omitted, it defaults to the ``DefaultRelation`` instance on the type of + the objects. By default, it means the most recent ``Equivalence`` instance + in the environment, but it can be customized by declaring + new ``DefaultRelation`` instances. As Leibniz equality is a declared + equivalence, it will fall back to it if no other relation is declared + on a given type. + +Every derived tactic that is based on the unprefixed forms of the +tactics considered above will also work up to user defined relations. +For instance, it is possible to register hints for :tacn:`autorewrite` that +are not proofs of Leibniz equalities. In particular it is possible to +exploit :tacn:`autorewrite` to simulate normalization in a term rewriting +system up to user defined equalities. + + +Printing relations and morphisms +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. cmd:: Print Instances + + This command can be used to show the list of currently + registered ``Reflexive`` (using ``Print Instances Reflexive``), ``Symmetric`` + or ``Transitive`` relations, Equivalences, PreOrders, PERs, and Morphisms + (implemented as ``Proper`` instances). When the rewriting tactics refuse + to replace a term in a context because the latter is not a composition + of morphisms, the :cmd:`Print Instances` command can be useful to understand + what additional morphisms should be registered. + + +Deprecated syntax and backward incompatibilities +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. cmd:: Add Setoid @A @Aeq @ST as @ident + + This command for declaring setoids and morphisms is also accepted due + to backward compatibility reasons. + + Here ``Aeq`` is a congruence relation without parameters, ``A`` is its carrier + and ``ST`` is an object of type (``Setoid_Theory A Aeq``) (i.e. a record + packing together the reflexivity, symmetry and transitivity lemmas). + Notice that the syntax is not completely backward compatible since the + identifier was not required. + +.. cmd:: Add Morphism f : @ident + :name: Add Morphism + + This command is restricted to the declaration of morphisms + without parameters. It is not fully backward compatible since the + property the user is asked to prove is slightly different: for n-ary + morphisms the hypotheses of the property are permuted; moreover, when + the morphism returns a proposition, the property is now stated using a + bi-implication in place of a simple implication. In practice, porting + an old development to the new semantics is usually quite simple. + +Notice that several limitations of the old implementation have been +lifted. In particular, it is now possible to declare several relations +with the same carrier and several signatures for the same morphism. +Moreover, it is now also possible to declare several morphisms having +the same signature. Finally, the :tacn:`replace` and :tacn:`rewrite` tactics can be +used to replace terms in contexts that were refused by the old +implementation. As discussed in the next section, the semantics of the +new :tacn:`setoid_rewrite` tactic differs slightly from the old one and +:tacn:`rewrite`. + + +Extensions +---------- + + +Rewriting under binders +~~~~~~~~~~~~~~~~~~~~~~~ + +.. warning:: + Due to compatibility issues, this feature is enabled only + when calling the :tacn:`setoid_rewrite` tactic directly and not :tacn:`rewrite`. + +To be able to rewrite under binding constructs, one must declare +morphisms with respect to pointwise (setoid) equivalence of functions. +Example of such morphisms are the standard ``all`` and ``ex`` combinators for +universal and existential quantification respectively. They are +declared as morphisms in the ``Classes.Morphisms_Prop`` module. For +example, to declare that universal quantification is a morphism for +logical equivalence: + +.. coqtop:: none + + Require Import Morphisms. + +.. coqtop:: in + + Instance all_iff_morphism (A : Type) : + Proper (pointwise_relation A iff ==> iff) (@all A). + +.. coqtop:: all abort + + Proof. simpl_relation. + +One then has to show that if two predicates are equivalent at every +point, their universal quantifications are equivalent. Once we have +declared such a morphism, it will be used by the setoid rewriting +tactic each time we try to rewrite under an ``all`` application (products +in ``Prop`` are implicitly translated to such applications). + +Indeed, when rewriting under a lambda, binding variable ``x``, say from ``P x`` +to ``Q x`` using the relation iff, the tactic will generate a proof of +``pointwise_relation A iff (fun x => P x) (fun x => Q x)`` from the proof +of ``iff (P x) (Q x)`` and a constraint of the form ``Proper (pointwise_relation A iff ==> ?) m`` +will be generated for the surrounding morphism ``m``. + +Hence, one can add higher-order combinators as morphisms by providing +signatures using pointwise extension for the relations on the +functional arguments (or whatever subrelation of the pointwise +extension). For example, one could declare the ``map`` combinator on lists +as a morphism: + +.. coqdoc:: + + Instance map_morphism `{Equivalence A eqA, Equivalence B eqB} : + Proper ((eqA ==> eqB) ==> list_equiv eqA ==> list_equiv eqB) (@map A B). + +where ``list_equiv`` implements an equivalence on lists parameterized by +an equivalence on the elements. + +Note that when one does rewriting with a lemma under a binder using +:tacn:`setoid_rewrite`, the application of the lemma may capture the bound +variable, as the semantics are different from rewrite where the lemma +is first matched on the whole term. With the new :tacn:`setoid_rewrite`, +matching is done on each subterm separately and in its local +environment, and all matches are rewritten *simultaneously* by +default. The semantics of the previous :tacn:`setoid_rewrite` implementation +can almost be recovered using the ``at 1`` modifier. + + +Subrelations +~~~~~~~~~~~~~ + +Subrelations can be used to specify that one relation is included in +another, so that morphism signatures for one can be used for the +other. If a signature mentions a relation ``R`` on the left of an +arrow ``==>``, then the signature also applies for any relation ``S`` that is +smaller than ``R``, and the inverse applies on the right of an arrow. One +can then declare only a few morphisms instances that generate the +complete set of signatures for a particular constant. By default, the +only declared subrelation is ``iff``, which is a subrelation of ``impl`` and +``inverse impl`` (the dual of implication). That’s why we can declare only +two morphisms for conjunction: ``Proper (impl ==> impl ==> impl) and`` and +``Proper (iff ==> iff ==> iff) and``. This is sufficient to satisfy any +rewriting constraints arising from a rewrite using ``iff``, ``impl`` or +``inverse impl`` through ``and``. + +Subrelations are implemented in ``Classes.Morphisms`` and are a prime +example of a mostly user-space extension of the algorithm. + + +Constant unfolding +~~~~~~~~~~~~~~~~~~ + +The resolution tactic is based on typeclasses and hence regards user- +defined constants as transparent by default. This may slow down the +resolution due to a lot of unifications (all the declared ``Proper`` +instances are tried at each node of the search tree). To speed it up, +declare your constant as rigid for proof search using the command +:cmd:`Typeclasses Opaque`. + +Strategies for rewriting +------------------------ + +Definitions +~~~~~~~~~~~ + +The generalized rewriting tactic is based on a set of strategies that can be +combined to obtain custom rewriting procedures. Its set of strategies is based +on Elan’s rewriting strategies :cite:`Luttik97specificationof`. Rewriting +strategies are applied using the tactic ``rewrite_strat s`` where ``s`` is a +strategy expression. Strategies are defined inductively as described by the +following grammar: + +.. productionlist:: rewriting + s, t, u : `strategy` + : `lemma` + : `lemma_right_to_left` + : `failure` + : `identity` + : `reflexivity` + : `progress` + : `failure_catch` + : `composition` + : `left_biased_choice` + : `iteration_one_or_more` + : `iteration_zero_or_more` + : `one_subterm` + : `all_subterms` + : `innermost_first` + : `outermost_first` + : `bottom_up` + : `top_down` + : `apply_hint` + : `any_of_the_terms` + : `apply_reduction` + : `fold_expression` + +.. productionlist:: rewriting + strategy : ( `s` ) + lemma : `c` + lemma_right_to_left : <- `c` + failure : fail + identity : id + reflexivity : refl + progress : progress `s` + failure_catch : try `s` + composition : `s` ; `u` + left_biased_choice : choice `s` `t` + iteration_one_or_more : repeat `s` + iteration_zero_or_more : any `s` + one_subterm : subterm `s` + all_subterms : subterms `s` + innermost_first : innermost `s` + outermost_first : outermost `s` + bottom_up : bottomup `s` + top_down : topdown `s` + apply_hint : hints `hintdb` + any_of_the_terms : terms (`c`)+ + apply_reduction : eval `redexpr` + fold_expression : fold `c` + + +Actually a few of these are defined in term of the others using a +primitive fixpoint operator: + +.. productionlist:: rewriting + try `s` : choice `s` `id` + any `s` : fix `u`. try (`s` ; `u`) + repeat `s` : `s` ; any `s` + bottomup s : fix `bu`. (choice (progress (subterms bu)) s) ; try bu + topdown s : fix `td`. (choice s (progress (subterms td))) ; try td + innermost s : fix `i`. (choice (subterm i) s) + outermost s : fix `o`. (choice s (subterm o)) + +The basic control strategy semantics are straightforward: strategies +are applied to subterms of the term to rewrite, starting from the root +of the term. The lemma strategies unify the left-hand-side of the +lemma with the current subterm and on success rewrite it to the right- +hand-side. Composition can be used to continue rewriting on the +current subterm. The fail strategy always fails while the identity +strategy succeeds without making progress. The reflexivity strategy +succeeds, making progress using a reflexivity proof of rewriting. +Progress tests progress of the argument strategy and fails if no +progress was made, while ``try`` always succeeds, catching failures. +Choice is left-biased: it will launch the first strategy and fall back +on the second one in case of failure. One can iterate a strategy at +least 1 time using ``repeat`` and at least 0 times using ``any``. + +The ``subterm`` and ``subterms`` strategies apply their argument strategy ``s`` to +respectively one or all subterms of the current term under +consideration, left-to-right. ``subterm`` stops at the first subterm for +which ``s`` made progress. The composite strategies ``innermost`` and ``outermost`` +perform a single innermost or outermost rewrite using their argument +strategy. Their counterparts ``bottomup`` and ``topdown`` perform as many +rewritings as possible, starting from the bottom or the top of the +term. + +Hint databases created for :tacn:`autorewrite` can also be used +by :tacn:`rewrite_strat` using the ``hints`` strategy that applies any of the +lemmas at the current subterm. The ``terms`` strategy takes the lemma +names directly as arguments. The ``eval`` strategy expects a reduction +expression (see :ref:`performingcomputations`) and succeeds +if it reduces the subterm under consideration. The ``fold`` strategy takes +a term ``c`` and tries to *unify* it to the current subterm, converting it to ``c`` +on success, it is stronger than the tactic ``fold``. + + +Usage +~~~~~ + + +.. tacn:: rewrite_strat @s [in @ident] + :name: rewrite_strat + + Rewrite using the strategy s in hypothesis ident or the conclusion. + + .. exn:: Nothing to rewrite. + + If the strategy failed. + + .. exn:: No progress made. + + If the strategy succeeded but made no progress. + + .. exn:: Unable to satisfy the rewriting constraints. + + If the strategy succeeded and made progress but the + corresponding rewriting constraints are not satisfied. + + + The ``setoid_rewrite c`` tactic is basically equivalent to + ``rewrite_strat (outermost c)``. + diff --git a/doc/sphinx/addendum/implicit-coercions.rst b/doc/sphinx/addendum/implicit-coercions.rst new file mode 100644 index 0000000000..d5523e8561 --- /dev/null +++ b/doc/sphinx/addendum/implicit-coercions.rst @@ -0,0 +1,469 @@ +.. _implicitcoercions: + +Implicit Coercions +==================== + +:Author: Amokrane Saïbi + +General Presentation +--------------------- + +This section describes the inheritance mechanism of |Coq|. In |Coq| with +inheritance, we are not interested in adding any expressive power to +our theory, but only convenience. Given a term, possibly not typable, +we are interested in the problem of determining if it can be well +typed modulo insertion of appropriate coercions. We allow to write: + + * :g:`f a` where :g:`f:(forall x:A,B)` and :g:`a:A'` when ``A'`` can + be seen in some sense as a subtype of ``A``. + * :g:`x:A` when ``A`` is not a type, but can be seen in + a certain sense as a type: set, group, category etc. + * :g:`f a` when ``f`` is not a function, but can be seen in a certain sense + as a function: bijection, functor, any structure morphism etc. + + +Classes +------- + +A class with :math:`n` parameters is any defined name with a type +:n:`forall (@ident__1 : @type__1)..(@ident__n:@type__n), @sort`. Thus a class with +parameters is considered as a single class and not as a family of +classes. An object of a class is any term of type :n:`@class @term__1 .. @term__n`. +In addition to these user-defined classes, we have two built-in classes: + + + * ``Sortclass``, the class of sorts; its objects are the terms whose type is a + sort (e.g. :g:`Prop` or :g:`Type`). + * ``Funclass``, the class of functions; its objects are all the terms with a functional + type, i.e. of form :g:`forall x:A,B`. + +Formally, the syntax of classes is defined as: + +.. productionlist:: + class: `qualid` + : Sortclass + : Funclass + + +Coercions +--------- + +A name ``f`` can be declared as a coercion between a source user-defined class +``C`` with :math:`n` parameters and a target class ``D`` if one of these +conditions holds: + + * ``D`` is a user-defined class, then the type of ``f`` must have the form + :g:`forall (x₁:A₁)..(xₙ:Aₙ)(y:C x₁..xₙ), D u₁..uₘ` where :math:`m` + is the number of parameters of ``D``. + * ``D`` is ``Funclass``, then the type of ``f`` must have the form + :g:`forall (x₁:A₁)..(xₙ:Aₙ)(y:C x₁..xₙ)(x:A), B`. + * ``D`` is ``Sortclass``, then the type of ``f`` must have the form + :g:`forall (x₁:A₁)..(xₙ:Aₙ)(y:C x₁..xₙ), s` with ``s`` a sort. + +We then write :g:`f : C >-> D`. The restriction on the type +of coercions is called *the uniform inheritance condition*. + +.. note:: The built-in class ``Sortclass`` can be used as a source class, but + the built-in class ``Funclass`` cannot. + +To coerce an object :g:`t:C t₁..tₙ` of ``C`` towards ``D``, we have to +apply the coercion ``f`` to it; the obtained term :g:`f t₁..tₙ t` is +then an object of ``D``. + + +Identity Coercions +------------------- + +Identity coercions are special cases of coercions used to go around +the uniform inheritance condition. Let ``C`` and ``D`` be two classes +with respectively `n` and `m` parameters and +:g:`f:forall (x₁:T₁)..(xₖ:Tₖ)(y:C u₁..uₙ), D v₁..vₘ` a function which +does not verify the uniform inheritance condition. To declare ``f`` as +coercion, one has first to declare a subclass ``C'`` of ``C``: + + :g:`C' := fun (x₁:T₁)..(xₖ:Tₖ) => C u₁..uₙ` + +We then define an *identity coercion* between ``C'`` and ``C``: + + :g:`Id_C'_C := fun (x₁:T₁)..(xₖ:Tₖ)(y:C' x₁..xₖ) => (y:C u₁..uₙ)` + +We can now declare ``f`` as coercion from ``C'`` to ``D``, since we can +"cast" its type as +:g:`forall (x₁:T₁)..(xₖ:Tₖ)(y:C' x₁..xₖ),D v₁..vₘ`. + +The identity coercions have a special status: to coerce an object +:g:`t:C' t₁..tₖ` +of ``C'`` towards ``C``, we do not have to insert explicitly ``Id_C'_C`` +since :g:`Id_C'_C t₁..tₖ t` is convertible with ``t``. However we +"rewrite" the type of ``t`` to become an object of ``C``; in this case, +it becomes :g:`C uₙ'..uₖ'` where each ``uᵢ'`` is the result of the +substitution in ``uᵢ`` of the variables ``xⱼ`` by ``tⱼ``. + +Inheritance Graph +------------------ + +Coercions form an inheritance graph with classes as nodes. We call +*coercion path* an ordered list of coercions between two nodes of +the graph. A class ``C`` is said to be a subclass of ``D`` if there is a +coercion path in the graph from ``C`` to ``D``; we also say that ``C`` +inherits from ``D``. Our mechanism supports multiple inheritance since a +class may inherit from several classes, contrary to simple inheritance +where a class inherits from at most one class. However there must be +at most one path between two classes. If this is not the case, only +the *oldest* one is valid and the others are ignored. So the order +of declaration of coercions is important. + +We extend notations for coercions to coercion paths. For instance +:g:`[f₁;..;fₖ] : C >-> D` is the coercion path composed +by the coercions ``f₁..fₖ``. The application of a coercion path to a +term consists of the successive application of its coercions. + + +Declaring Coercions +------------------------- + +.. cmd:: Coercion @qualid : @class >-> @class + + Declares the construction denoted by :token:`qualid` as a coercion between + the two given classes. + + .. exn:: @qualid not declared. + :undocumented: + + .. exn:: @qualid is already a coercion. + :undocumented: + + .. exn:: Funclass cannot be a source class. + :undocumented: + + .. exn:: @qualid is not a function. + :undocumented: + + .. exn:: Cannot find the source class of @qualid. + :undocumented: + + .. exn:: Cannot recognize @class as a source class of @qualid. + :undocumented: + + .. exn:: @qualid does not respect the uniform inheritance condition. + :undocumented: + + .. exn:: Found target class ... instead of ... + :undocumented: + + .. warn:: Ambiguous path. + + When the coercion :token:`qualid` is added to the inheritance graph, + invalid coercion paths are ignored. The :cmd:`Coercion` command tries to check + that they are convertible with existing ones on the same classes. + The paths for which this check fails are displayed by a warning in the form + :g:`[f₁;..;fₙ] : C >-> D`. + + .. cmdv:: Local Coercion @qualid : @class >-> @class + + Declares the construction denoted by :token:`qualid` as a coercion local to + the current section. + + .. cmdv:: Coercion @ident := @term {? @type } + + This defines :token:`ident` just like :n:`Definition @ident := term {? @type }`, + and then declares :token:`ident` as a coercion between it source and its target. + + .. cmdv:: Local Coercion @ident := @term {? @type } + + This defines :token:`ident` just like :n:`Let @ident := @term {? @type }`, + and then declares :token:`ident` as a coercion between it source and its target. + +Assumptions can be declared as coercions at declaration time. +This extends the grammar of assumptions from +Figure :ref:`vernacular` as follows: + +.. + FIXME: + \comindex{Variable \mbox{\rm (and coercions)}} + \comindex{Axiom \mbox{\rm (and coercions)}} + \comindex{Parameter \mbox{\rm (and coercions)}} + \comindex{Hypothesis \mbox{\rm (and coercions)}} + +.. productionlist:: + assumption : `assumption_keyword` `assums` . + assums : `simple_assums` + : (`simple_assums`) ... (`simple_assums`) + simple_assums : `ident` ... `ident` :[>] `term` + +If the extra ``>`` is present before the type of some assumptions, these +assumptions are declared as coercions. + +Similarly, constructors of inductive types can be declared as coercions at +definition time of the inductive type. This extends and modifies the +grammar of inductive types from Figure :ref:`vernacular` as follows: + +.. + FIXME: + \comindex{Inductive \mbox{\rm (and coercions)}} + \comindex{CoInductive \mbox{\rm (and coercions)}} + +.. productionlist:: + inductive : Inductive `ind_body` with ... with `ind_body` + : CoInductive `ind_body` with ... with `ind_body` + ind_body : `ident` [ `binders` ] : `term` := [[|] `constructor` | ... | `constructor` ] + constructor : `ident` [ `binders` ] [:[>] `term` ] + +Especially, if the extra ``>`` is present in a constructor +declaration, this constructor is declared as a coercion. + +.. cmd:: Identity Coercion @ident : @class >-> @class + + If ``C`` is the source `class` and ``D`` the destination, we check + that ``C`` is a constant with a body of the form + :g:`fun (x₁:T₁)..(xₙ:Tₙ) => D t₁..tₘ` where `m` is the + number of parameters of ``D``. Then we define an identity + function with type :g:`forall (x₁:T₁)..(xₙ:Tₙ)(y:C x₁..xₙ),D t₁..tₘ`, + and we declare it as an identity coercion between ``C`` and ``D``. + + .. exn:: @class must be a transparent constant. + :undocumented: + + .. cmdv:: Local Identity Coercion @ident : @ident >-> @ident + + Same as :cmd:`Identity Coercion` but locally to the current section. + + .. cmdv:: SubClass @ident := @type + :name: SubClass + + If :n:`@type` is a class :n:`@ident'` applied to some arguments then + :n:`@ident` is defined and an identity coercion of name + :n:`Id_@ident_@ident'` is + declared. Otherwise said, this is an abbreviation for + + :n:`Definition @ident := @type.` + :n:`Identity Coercion Id_@ident_@ident' : @ident >-> @ident'`. + + .. cmdv:: Local SubClass @ident := @type + + Same as before but locally to the current section. + + +Displaying Available Coercions +------------------------------- + +.. cmd:: Print Classes + + Print the list of declared classes in the current context. + +.. cmd:: Print Coercions + + Print the list of declared coercions in the current context. + +.. cmd:: Print Graph + + Print the list of valid coercion paths in the current context. + +.. cmd:: Print Coercion Paths @class @class + + Print the list of valid coercion paths between the two given classes. + +Activating the Printing of Coercions +------------------------------------- + +.. flag:: Printing Coercions + + When on, this option forces all the coercions to be printed. + By default, coercions are not printed. + +.. table:: Printing Coercion @qualid + :name: Printing Coercion + + Specifies a set of qualids for which coercions are always displayed. Use the + :cmd:`Add @table` and :cmd:`Remove @table` commands to update the set of qualids. + +.. _coercions-classes-as-records: + +Classes as Records +------------------ + +.. index:: :> (coercion) + +We allow the definition of *Structures with Inheritance* (or classes as records) +by extending the existing :cmd:`Record` macro. Its new syntax is: + +.. cmdv:: Record {? >} @ident {? @binders} : @sort := {? @ident} { {+; @ident :{? >} @term } } + + The first identifier :token:`ident` is the name of the defined record and + :token:`sort` is its type. The optional identifier after ``:=`` is the name + of the constructor (it will be :n:`Build_@ident` if not given). + The other identifiers are the names of the fields, and :token:`term` + are their respective types. If ``:>`` is used instead of ``:`` in + the declaration of a field, then the name of this field is automatically + declared as a coercion from the record name to the class of this + field type. Note that the fields always verify the uniform + inheritance condition. If the optional ``>`` is given before the + record name, then the constructor name is automatically declared as + a coercion from the class of the last field type to the record name + (this may fail if the uniform inheritance condition is not + satisfied). + +.. cmdv:: Structure {? >} @ident {? @binders} : @sort := {? @ident} { {+; @ident :{? >} @term } } + :name: Structure + + This is a synonym of :cmd:`Record`. + + +Coercions and Sections +---------------------- + +The inheritance mechanism is compatible with the section +mechanism. The global classes and coercions defined inside a section +are redefined after its closing, using their new value and new +type. The classes and coercions which are local to the section are +simply forgotten. +Coercions with a local source class or a local target class, and +coercions which do not verify the uniform inheritance condition any longer +are also forgotten. + +Coercions and Modules +--------------------- + +The coercions present in a module are activated only when the module is +explicitly imported. + +Examples +-------- + +There are three situations: + +Coercion at function application +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +:g:`f a` is ill-typed where :g:`f:forall x:A,B` and :g:`a:A'`. If there is a +coercion path between ``A'`` and ``A``, then :g:`f a` is transformed into +:g:`f a'` where ``a'`` is the result of the application of this +coercion path to ``a``. + +We first give an example of coercion between atomic inductive types + +.. coqtop:: all + + Definition bool_in_nat (b:bool) := if b then 0 else 1. + Coercion bool_in_nat : bool >-> nat. + Check (0 = true). + Set Printing Coercions. + Check (0 = true). + Unset Printing Coercions. + + +.. warning:: + + Note that ``Check (true = O)`` would fail. This is "normal" behavior of + coercions. To validate ``true=O``, the coercion is searched from + ``nat`` to ``bool``. There is none. + +We give an example of coercion between classes with parameters. + +.. coqtop:: all + + Parameters (C : nat -> Set) (D : nat -> bool -> Set) (E : bool -> Set). + Parameter f : forall n:nat, C n -> D (S n) true. + Coercion f : C >-> D. + Parameter g : forall (n:nat) (b:bool), D n b -> E b. + Coercion g : D >-> E. + Parameter c : C 0. + Parameter T : E true -> nat. + Check (T c). + Set Printing Coercions. + Check (T c). + Unset Printing Coercions. + +We give now an example using identity coercions. + +.. coqtop:: all + + Definition D' (b:bool) := D 1 b. + Identity Coercion IdD'D : D' >-> D. + Print IdD'D. + Parameter d' : D' true. + Check (T d'). + Set Printing Coercions. + Check (T d'). + Unset Printing Coercions. + + +In the case of functional arguments, we use the monotonic rule of +sub-typing. To coerce :g:`t : forall x : A, B` towards +:g:`forall x : A', B'`, we have to coerce ``A'`` towards ``A`` and ``B`` +towards ``B'``. An example is given below: + +.. coqtop:: all + + Parameters (A B : Set) (h : A -> B). + Coercion h : A >-> B. + Parameter U : (A -> E true) -> nat. + Parameter t : B -> C 0. + Check (U t). + Set Printing Coercions. + Check (U t). + Unset Printing Coercions. + +Remark the changes in the result following the modification of the +previous example. + +.. coqtop:: all + + Parameter U' : (C 0 -> B) -> nat. + Parameter t' : E true -> A. + Check (U' t'). + Set Printing Coercions. + Check (U' t'). + Unset Printing Coercions. + + +Coercion to a type +~~~~~~~~~~~~~~~~~~ + +An assumption ``x:A`` when ``A`` is not a type, is ill-typed. It is +replaced by ``x:A'`` where ``A'`` is the result of the application to +``A`` of the coercion path between the class of ``A`` and +``Sortclass`` if it exists. This case occurs in the abstraction +:g:`fun x:A => t`, universal quantification :g:`forall x:A,B`, global +variables and parameters of (co-)inductive definitions and +functions. In :g:`forall x:A,B`, such a coercion path may also be applied +to ``B`` if necessary. + +.. coqtop:: all + + Parameter Graph : Type. + Parameter Node : Graph -> Type. + Coercion Node : Graph >-> Sortclass. + Parameter G : Graph. + Parameter Arrows : G -> G -> Type. + Check Arrows. + Parameter fg : G -> G. + Check fg. + Set Printing Coercions. + Check fg. + Unset Printing Coercions. + + +Coercion to a function +~~~~~~~~~~~~~~~~~~~~~~ + +``f a`` is ill-typed because ``f:A`` is not a function. The term +``f`` is replaced by the term obtained by applying to ``f`` the +coercion path between ``A`` and ``Funclass`` if it exists. + +.. coqtop:: all + + Parameter bij : Set -> Set -> Set. + Parameter ap : forall A B:Set, bij A B -> A -> B. + Coercion ap : bij >-> Funclass. + Parameter b : bij nat nat. + Check (b 0). + Set Printing Coercions. + Check (b 0). + Unset Printing Coercions. + +Let us see the resulting graph after all these examples. + +.. coqtop:: all + + Print Graph. diff --git a/doc/sphinx/addendum/micromega.rst b/doc/sphinx/addendum/micromega.rst new file mode 100644 index 0000000000..e56b36caad --- /dev/null +++ b/doc/sphinx/addendum/micromega.rst @@ -0,0 +1,271 @@ +.. _ micromega: + +Micromega: tactics for solving arithmetic goals over ordered rings +================================================================== + +:Authors: Frédéric Besson and Evgeny Makarov + +Short description of the tactics +-------------------------------- + +The Psatz module (``Require Import Psatz.``) gives access to several +tactics for solving arithmetic goals over :math:`\mathbb{Z}`, :math:`\mathbb{Q}`, and :math:`\mathbb{R}` [#]_. +It also possible to get the tactics for integers by a ``Require Import Lia``, +rationals ``Require Import Lqa`` and reals ``Require Import Lra``. + ++ :tacn:`lia` is a decision procedure for linear integer arithmetic; ++ :tacn:`nia` is an incomplete proof procedure for integer non-linear + arithmetic; ++ :tacn:`lra` is a decision procedure for linear (real or rational) arithmetic; ++ :tacn:`nra` is an incomplete proof procedure for non-linear (real or + rational) arithmetic; ++ :tacn:`psatz` ``D n`` where ``D`` is :math:`\mathbb{Z}` or :math:`\mathbb{Q}` or :math:`\mathbb{R}`, and + ``n`` is an optional integer limiting the proof search depth, + is an incomplete proof procedure for non-linear arithmetic. + It is based on John Harrison’s HOL Light + driver to the external prover `csdp` [#]_. Note that the `csdp` driver is + generating a *proof cache* which makes it possible to rerun scripts + even without `csdp`. + +.. flag:: Simplex + + This option (set by default) instructs the decision procedures to + use the Simplex method for solving linear goals. If it is not set, + the decision procedures are using Fourier elimination. + + +The tactics solve propositional formulas parameterized by atomic +arithmetic expressions interpreted over a domain :math:`D \in \{\mathbb{Z},\mathbb{Q},\mathbb{R}\}`. +The syntax of the formulas is the following: + + .. productionlist:: F + F : A ∣ P ∣ True ∣ False ∣ F ∧ F ∣ F ∨ F ∣ F ↔ F ∣ F → F ∣ ¬ F + A : p = p ∣ p > p ∣ p < p ∣ p ≥ p ∣ p ≤ p + p : c ∣ x ∣ −p ∣ p − p ∣ p + p ∣ p × p ∣ p ^ n + +where :math:`c` is a numeric constant, :math:`x \in D` is a numeric variable, the +operators :math:`−, +, ×` are respectively subtraction, addition, and product; +:math:`p ^ n` is exponentiation by a constant :math:`n`, :math:`P` is an arbitrary proposition. +For :math:`\mathbb{Q}`, equality is not Leibniz equality ``=`` but the equality of +rationals ``==``. + +For :math:`\mathbb{Z}` (resp. :math:`\mathbb{Q}`), :math:`c` ranges over integer constants (resp. rational +constants). For :math:`\mathbb{R}`, the tactic recognizes as real constants the +following expressions: + +:: + + c ::= R0 | R1 | Rmul(c,c) | Rplus(c,c) | Rminus(c,c) | IZR z | IQR q | Rdiv(c,c) | Rinv c + +where :math:`z` is a constant in :math:`\mathbb{Z}` and :math:`q` is a constant in :math:`\mathbb{Q}`. +This includes integer constants written using the decimal notation, *i.e.*, ``c%R``. + + +*Positivstellensatz* refutations +-------------------------------- + +The name `psatz` is an abbreviation for *positivstellensatz* – literally +"positivity theorem" – which generalizes Hilbert’s *nullstellensatz*. It +relies on the notion of Cone. Given a (finite) set of polynomials :math:`S`, +:math:`\mathit{Cone}(S)` is inductively defined as the smallest set of polynomials +closed under the following rules: + +:math:`\begin{array}{l} +\dfrac{p \in S}{p \in \mathit{Cone}(S)} \quad +\dfrac{}{p^2 \in \mathit{Cone}(S)} \quad +\dfrac{p_1 \in \mathit{Cone}(S) \quad p_2 \in \mathit{Cone}(S) \quad +\Join \in \{+,*\}} {p_1 \Join p_2 \in \mathit{Cone}(S)}\\ +\end{array}` + +The following theorem provides a proof principle for checking that a +set of polynomial inequalities does not have solutions [#]_. + +.. _psatz_thm: + +**Theorem (Psatz)**. Let :math:`S` be a set of polynomials. +If :math:`-1` belongs to :math:`\mathit{Cone}(S)`, then the conjunction +:math:`\bigwedge_{p \in S} p\ge 0` is unsatisfiable. +A proof based on this theorem is called a *positivstellensatz* +refutation. The tactics work as follows. Formulas are normalized into +conjunctive normal form :math:`\bigwedge_i C_i` where :math:`C_i` has the +general form :math:`(\bigwedge_{j\in S_i} p_j \Join 0) \to \mathit{False}` and +:math:`\Join \in \{>,\ge,=\}` for :math:`D\in \{\mathbb{Q},\mathbb{R}\}` and +:math:`\Join \in \{\ge, =\}` for :math:`\mathbb{Z}`. + +For each conjunct :math:`C_i`, the tactic calls an oracle which searches for +:math:`-1` within the cone. Upon success, the oracle returns a *cone +expression* that is normalized by the :tacn:`ring` tactic (see :ref:`theringandfieldtacticfamilies`) +and checked to be :math:`-1`. + +`lra`: a decision procedure for linear real and rational arithmetic +------------------------------------------------------------------- + +.. tacn:: lra + :name: lra + + This tactic is searching for *linear* refutations. As a result, this tactic explores a subset of the *Cone* + defined as + + :math:`\mathit{LinCone}(S) =\left\{ \left. \sum_{p \in S} \alpha_p \times p~\right|~\alpha_p \mbox{ are positive constants} \right\}` + + The deductive power of :tacn:`lra` overlaps with the one of :tacn:`field` + tactic *e.g.*, :math:`x = 10 * x / 10` is solved by :tacn:`lra`. + + +`lia`: a tactic for linear integer arithmetic +--------------------------------------------- + +.. tacn:: lia + :name: lia + + This tactic offers an alternative to the :tacn:`omega` tactic. Roughly + speaking, the deductive power of lia is the combined deductive power of + :tacn:`ring_simplify` and :tacn:`omega`. However, it solves linear goals + that :tacn:`omega` does not solve, such as the following so-called *omega + nightmare* :cite:`TheOmegaPaper`. + +.. coqdoc:: + + Goal forall x y, + 27 <= 11 * x + 13 * y <= 45 -> + -10 <= 7 * x - 9 * y <= 4 -> False. + +The estimation of the relative efficiency of :tacn:`lia` *vs* :tacn:`omega` is under evaluation. + +High level view of `lia` +~~~~~~~~~~~~~~~~~~~~~~~~ + +Over :math:`\mathbb{R}`, *positivstellensatz* refutations are a complete proof +principle [#]_. However, this is not the case over :math:`\mathbb{Z}`. Actually, +*positivstellensatz* refutations are not even sufficient to decide +linear *integer* arithmetic. The canonical example is :math:`2 * x = 1 -> \mathtt{False}` +which is a theorem of :math:`\mathbb{Z}` but not a theorem of :math:`{\mathbb{R}}`. To remedy this +weakness, the :tacn:`lia` tactic is using recursively a combination of: + ++ linear *positivstellensatz* refutations; ++ cutting plane proofs; ++ case split. + +Cutting plane proofs +~~~~~~~~~~~~~~~~~~~~~~ + +are a way to take into account the discreteness of :math:`\mathbb{Z}` by rounding up +(rational) constants up-to the closest integer. + +.. _ceil_thm: + +.. thm:: Bound on the ceiling function + + Let :math:`p` be an integer and :math:`c` a rational constant. Then + :math:`p \ge c \rightarrow p \ge \lceil{c}\rceil`. + +For instance, from 2 x = 1 we can deduce + ++ :math:`x \ge 1/2` whose cut plane is :math:`x \ge \lceil{1/2}\rceil = 1`; ++ :math:`x \le 1/2` whose cut plane is :math:`x \le \lfloor{1/2}\rfloor = 0`. + +By combining these two facts (in normal form) :math:`x − 1 \ge 0` and +:math:`-x \ge 0`, we conclude by exhibiting a *positivstellensatz* refutation: +:math:`−1 \equiv x−1 + −x \in \mathit{Cone}({x−1,x})`. + +Cutting plane proofs and linear *positivstellensatz* refutations are a +complete proof principle for integer linear arithmetic. + +Case split +~~~~~~~~~~~ + +enumerates over the possible values of an expression. + +.. _casesplit_thm: + +**Theorem**. Let :math:`p` be an integer and :math:`c_1` and :math:`c_2` +integer constants. Then: + + :math:`c_1 \le p \le c_2 \Rightarrow \bigvee_{x \in [c_1,c_2]} p = x` + +Our current oracle tries to find an expression :math:`e` with a small range +:math:`[c_1,c_2]`. We generate :math:`c_2 − c_1` subgoals which contexts are enriched +with an equation :math:`e = i` for :math:`i \in [c_1,c_2]` and recursively search for +a proof. + +`nra`: a proof procedure for non-linear arithmetic +-------------------------------------------------- + +.. tacn:: nra + :name: nra + + This tactic is an *experimental* proof procedure for non-linear + arithmetic. The tactic performs a limited amount of non-linear + reasoning before running the linear prover of :tacn:`lra`. This pre-processing + does the following: + + ++ If the context contains an arithmetic expression of the form + :math:`e[x^2]` where :math:`x` is a monomial, the context is enriched with + :math:`x^2 \ge 0`; ++ For all pairs of hypotheses :math:`e_1 \ge 0`, :math:`e_2 \ge 0`, the context is + enriched with :math:`e_1 \times e_2 \ge 0`. + +After this pre-processing, the linear prover of :tacn:`lra` searches for a +proof by abstracting monomials by variables. + +`nia`: a proof procedure for non-linear integer arithmetic +---------------------------------------------------------- + +.. tacn:: nia + :name: nia + + This tactic is a proof procedure for non-linear integer arithmetic. + It performs a pre-processing similar to :tacn:`nra`. The obtained goal is + solved using the linear integer prover :tacn:`lia`. + +`psatz`: a proof procedure for non-linear arithmetic +---------------------------------------------------- + +.. tacn:: psatz + :name: psatz + + This tactic explores the *Cone* by increasing degrees – hence the + depth parameter *n*. In theory, such a proof search is complete – if the + goal is provable the search eventually stops. Unfortunately, the + external oracle is using numeric (approximate) optimization techniques + that might miss a refutation. + + To illustrate the working of the tactic, consider we wish to prove the + following Coq goal: + +.. needs csdp +.. coqdoc:: + + Require Import ZArith Psatz. + Open Scope Z_scope. + Goal forall x, -x^2 >= 0 -> x - 1 >= 0 -> False. + intro x. + psatz Z 2. + +As shown, such a goal is solved by ``intro x. psatz Z 2.``. The oracle returns the +cone expression :math:`2 \times (x-1) + (\mathbf{x-1}) \times (\mathbf{x−1}) + -x^2` +(polynomial hypotheses are printed in bold). By construction, this expression +belongs to :math:`\mathit{Cone}({−x^2,x -1})`. Moreover, by running :tacn:`ring` we +obtain :math:`-1`. By Theorem :ref:`Psatz <psatz_thm>`, the goal is valid. + +.. [#] Support for :g:`nat` and :g:`N` is obtained by pre-processing the goal with + the ``zify`` tactic. +.. [#] Support for :g:`Z.div` and :g:`Z.modulo` may be obtained by + pre-processing the goal with the ``Z.div_mod_to_equations`` tactic (you may + need to manually run ``zify`` first). +.. [#] Support for :g:`Z.quot` and :g:`Z.rem` may be obtained by pre-processing + the goal with the ``Z.quot_rem_to_equations`` tactic (you may need to manually + run ``zify`` first). +.. [#] Note that support for :g:`Z.div`, :g:`Z.modulo`, :g:`Z.quot`, and + :g:`Z.rem` may be simultaneously obtained by pre-processing the goal with the + ``Z.to_euclidean_division_equations`` tactic (you may need to manually run + ``zify`` first). +.. [#] Sources and binaries can be found at https://projects.coin-or.org/Csdp +.. [#] Variants deal with equalities and strict inequalities. +.. [#] In practice, the oracle might fail to produce such a refutation. + +.. comment in original TeX: +.. %% \paragraph{The {\tt sos} tactic} -- where {\tt sos} stands for \emph{sum of squares} -- tries to prove that a +.. %% single polynomial $p$ is positive by expressing it as a sum of squares \emph{i.e.,} $\sum_{i\in S} p_i^2$. +.. %% This amounts to searching for $p$ in the cone without generators \emph{i.e.}, $Cone(\{\})$. diff --git a/doc/sphinx/addendum/miscellaneous-extensions.rst b/doc/sphinx/addendum/miscellaneous-extensions.rst new file mode 100644 index 0000000000..db8c09d88f --- /dev/null +++ b/doc/sphinx/addendum/miscellaneous-extensions.rst @@ -0,0 +1,58 @@ +.. _miscellaneousextensions: + +Miscellaneous extensions +======================== + +Program derivation +------------------ + +|Coq| comes with an extension called ``Derive``, which supports program +derivation. Typically in the style of Bird and Meertens or derivations +of program refinements. To use the Derive extension it must first be +required with ``Require Coq.derive.Derive``. When the extension is loaded, +it provides the following command: + +.. cmd:: Derive @ident__1 SuchThat @type As @ident__2 + + :n:`@ident__1` can appear in :n:`@type`. This command opens a new proof + presenting the user with a goal for :n:`@type` in which the name :n:`@ident__1` is + bound to an existential variable :g:`?x` (formally, there are other goals + standing for the existential variables but they are shelved, as + described in :tacn:`shelve`). + + When the proof ends two constants are defined: + + + The first one is named :n:`@ident__1` and is defined as the proof of the + shelved goal (which is also the value of :g:`?x`). It is always + transparent. + + The second one is named :n:`@ident__2`. It has type :n:`@type`, and its body is + the proof of the initially visible goal. It is opaque if the proof + ends with :cmd:`Qed`, and transparent if the proof ends with :cmd:`Defined`. + +.. example:: + + .. coqtop:: all + + Require Coq.derive.Derive. + Require Import Coq.Numbers.Natural.Peano.NPeano. + + Section P. + + Variables (n m k:nat). + + Derive p SuchThat ((k*n)+(k*m) = p) As h. + Proof. + rewrite <- Nat.mul_add_distr_l. + subst p. + reflexivity. + Qed. + + End P. + + Print p. + Check h. + +Any property can be used as `term`, not only an equation. In particular, +it could be an order relation specifying some form of program +refinement or a non-executable property from which deriving a program +is convenient. diff --git a/doc/sphinx/addendum/nsatz.rst b/doc/sphinx/addendum/nsatz.rst new file mode 100644 index 0000000000..ed2e1ea58c --- /dev/null +++ b/doc/sphinx/addendum/nsatz.rst @@ -0,0 +1,88 @@ +.. _nsatz_chapter: + +Nsatz: tactics for proving equalities in integral domains +=========================================================== + +:Author: Loïc Pottier + +.. tacn:: nsatz + :name: nsatz + + This tactic is for solving goals of the form + + :math:`\begin{array}{l} + \forall X_1, \ldots, X_n \in A, \\ + P_1(X_1, \ldots, X_n) = Q_1(X_1, \ldots, X_n), \ldots, P_s(X_1, \ldots, X_n) = Q_s(X_1, \ldots, X_n) \\ + \vdash P(X_1, \ldots, X_n) = Q(X_1, \ldots, X_n) \\ + \end{array}` + + where :math:`P, Q, P_1, Q_1, \ldots, P_s, Q_s` are polynomials and :math:`A` is an integral + domain, i.e. a commutative ring with no zero divisors. For example, :math:`A` + can be :math:`\mathbb{R}`, :math:`\mathbb{Z}`, or :math:`\mathbb{Q}`. + Note that the equality :math:`=` used in these goals can be + any setoid equality (see :ref:`tactics-enabled-on-user-provided-relations`) , not only Leibniz equality. + + It also proves formulas + + :math:`\begin{array}{l} + \forall X_1, \ldots, X_n \in A, \\ + P_1(X_1, \ldots, X_n) = Q_1(X_1, \ldots, X_n) \wedge \ldots \wedge P_s(X_1, \ldots, X_n) = Q_s(X_1, \ldots, X_n) \\ + \rightarrow P(X_1, \ldots, X_n) = Q(X_1, \ldots, X_n) \\ + \end{array}` + + doing automatic introductions. + + You can load the ``Nsatz`` module with the command ``Require Import Nsatz``. + +More about `nsatz` +--------------------- + +Hilbert’s Nullstellensatz theorem shows how to reduce proofs of +equalities on polynomials on a commutative ring :math:`A` with no zero divisors +to algebraic computations: it is easy to see that if a polynomial :math:`P` in +:math:`A[X_1,\ldots,X_n]` verifies :math:`c P^r = \sum_{i=1}^{s} S_i P_i`, with +:math:`c \in A`, :math:`c \not = 0`, +:math:`r` a positive integer, and the :math:`S_i` s in :math:`A[X_1,\ldots,X_n ]`, +then :math:`P` is zero whenever polynomials :math:`P_1,\ldots,P_s` are zero +(the converse is also true when :math:`A` is an algebraically closed field: the method is +complete). + +So, solving our initial problem reduces to finding :math:`S_1, \ldots, S_s`, +:math:`c` and :math:`r` such that :math:`c (P-Q)^r = \sum_{i} S_i (P_i-Q_i)`, +which will be proved by the tactic ring. + +This is achieved by the computation of a Gröbner basis of the ideal +generated by :math:`P_1-Q_1,...,P_s-Q_s`, with an adapted version of the +Buchberger algorithm. + +This computation is done after a step of *reification*, which is +performed using :ref:`typeclasses`. + +.. tacv:: nsatz with radicalmax:=@num%N strategy:=@num%Z parameters:=[{*, @ident}] variables:=[{*, @ident}] + + Most complete syntax for `nsatz`. + + * `radicalmax` is a bound when searching for r such that + :math:`c (P−Q) r = \sum_{i=1..s} S_i (P i − Q i)` + + * `strategy` gives the order on variables :math:`X_1,\ldots,X_n` and the strategy + used in Buchberger algorithm (see :cite:`sugar` for details): + + * strategy = 0: reverse lexicographic order and newest s-polynomial. + * strategy = 1: reverse lexicographic order and sugar strategy. + * strategy = 2: pure lexicographic order and newest s-polynomial. + * strategy = 3: pure lexicographic order and sugar strategy. + + * `parameters` is the list of variables :math:`X_{i_1},\ldots,X_{i_k}` among + :math:`X_1,\ldots,X_n` which are considered as parameters: computation will be performed with + rational fractions in these variables, i.e. polynomials are considered + with coefficients in :math:`R(X_{i_1},\ldots,X_{i_k})`. In this case, the coefficient + :math:`c` can be a non constant polynomial in :math:`X_{i_1},\ldots,X_{i_k}`, and the tactic + produces a goal which states that :math:`c` is not zero. + + * `variables` is the list of the variables in the decreasing order in + which they will be used in the Buchberger algorithm. If `variables` = :g:`(@nil R)`, + then `lvar` is replaced by all the variables which are not in + `parameters`. + +See the file `Nsatz.v` for many examples, especially in geometry. diff --git a/doc/sphinx/addendum/omega.rst b/doc/sphinx/addendum/omega.rst new file mode 100644 index 0000000000..b008508bbc --- /dev/null +++ b/doc/sphinx/addendum/omega.rst @@ -0,0 +1,187 @@ +.. _omega: + +Omega: a solver for quantifier-free problems in Presburger Arithmetic +===================================================================== + +:Author: Pierre Crégut + +Description of ``omega`` +------------------------ + +.. tacn:: omega + + :tacn:`omega` is a tactic for solving goals in Presburger arithmetic, + i.e. for proving formulas made of equations and inequalities over the + type ``nat`` of natural numbers or the type ``Z`` of binary-encoded integers. + Formulas on ``nat`` are automatically injected into ``Z``. The procedure + may use any hypothesis of the current proof session to solve the goal. + + Multiplication is handled by :tacn:`omega` but only goals where at + least one of the two multiplicands of products is a constant are + solvable. This is the restriction meant by "Presburger arithmetic". + + If the tactic cannot solve the goal, it fails with an error message. + In any case, the computation eventually stops. + +Arithmetical goals recognized by ``omega`` +------------------------------------------ + +:tacn:`omega` applies only to quantifier-free formulas built from the connectives:: + + /\ \/ ~ -> + +on atomic formulas. Atomic formulas are built from the predicates:: + + = < <= > >= + +on ``nat`` or ``Z``. In expressions of type ``nat``, :tacn:`omega` recognizes:: + + + - * S O pred + +and in expressions of type ``Z``, :tacn:`omega` recognizes numeral constants and:: + + + - * Z.succ Z.pred + +All expressions of type ``nat`` or ``Z`` not built on these +operators are considered abstractly as if they +were arbitrary variables of type ``nat`` or ``Z``. + +Messages from ``omega`` +----------------------- + +When :tacn:`omega` does not solve the goal, one of the following errors +is generated: + +.. exn:: omega can't solve this system. + + This may happen if your goal is not quantifier-free (if it is + universally quantified, try :tacn:`intros` first; if it contains + existentials quantifiers too, :tacn:`omega` is not strong enough to solve your + goal). This may happen also if your goal contains arithmetical + operators not recognized by :tacn:`omega`. Finally, your goal may be simply + not true! + +.. exn:: omega: Not a quantifier-free goal. + + If your goal is universally quantified, you should first apply + :tacn:`intro` as many times as needed. + +.. exn:: omega: Unrecognized predicate or connective: @ident. + :undocumented: + +.. exn:: omega: Unrecognized atomic proposition: ... + :undocumented: + +.. exn:: omega: Can't solve a goal with proposition variables. + :undocumented: + +.. exn:: omega: Unrecognized proposition. + :undocumented: + +.. exn:: omega: Can't solve a goal with non-linear products. + :undocumented: + +.. exn:: omega: Can't solve a goal with equality on type ... + :undocumented: + + +Using ``omega`` +--------------- + +The ``omega`` tactic does not belong to the core system. It should be +loaded by + +.. coqtop:: in + + Require Import Omega. + +.. example:: + + .. coqtop:: all + + Require Import Omega. + + Open Scope Z_scope. + + Goal forall m n:Z, 1 + 2 * m <> 2 * n. + intros; omega. + Abort. + + Goal forall z:Z, z > 0 -> 2 * z + 1 > z. + intro; omega. + Abort. + + +Options +------- + +.. flag:: Stable Omega + + .. deprecated:: 8.5 + + This deprecated option (on by default) is for compatibility with Coq pre 8.5. It + resets internal name counters to make executions of :tacn:`omega` independent. + +.. flag:: Omega UseLocalDefs + + This option (on by default) allows :tacn:`omega` to use the bodies of local + variables. + +.. flag:: Omega System + + This option (off by default) activate the printing of debug information + +.. flag:: Omega Action + + This option (off by default) activate the printing of debug information + +Technical data +-------------- + +Overview of the tactic +~~~~~~~~~~~~~~~~~~~~~~ + + * The goal is negated twice and the first negation is introduced as a hypothesis. + * Hypotheses are decomposed in simple equations or inequalities. Multiple + goals may result from this phase. + * Equations and inequalities over ``nat`` are translated over + ``Z``, multiple goals may result from the translation of subtraction. + * Equations and inequalities are normalized. + * Goals are solved by the OMEGA decision procedure. + * The script of the solution is replayed. + +Overview of the OMEGA decision procedure +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +The OMEGA decision procedure involved in the :tacn:`omega` tactic uses +a small subset of the decision procedure presented in :cite:`TheOmegaPaper` +Here is an overview, refer to the original paper for more information. + + * Equations and inequalities are normalized by division by the GCD of their + coefficients. + * Equations are eliminated, using the Banerjee test to get a coefficient + equal to one. + * Note that each inequality cuts the Euclidean space in half. + * Inequalities are solved by projecting on the hyperspace + defined by cancelling one of the variables. They are partitioned + according to the sign of the coefficient of the eliminated + variable. Pairs of inequalities from different classes define a + new edge in the projection. + * Redundant inequalities are eliminated or merged in new + equations that can be eliminated by the Banerjee test. + * The last two steps are iterated until a contradiction is reached + (success) or there is no more variable to eliminate (failure). + +It may happen that there is a real solution and no integer one. The last +steps of the Omega procedure are not implemented, so the +decision procedure is only partial. + +Bugs +---- + + * The simplification procedure is very dumb and this results in + many redundant cases to explore. + + * Much too slow. + + * Certainly other bugs! You can report them to https://coq.inria.fr/bugs/. diff --git a/doc/sphinx/addendum/parallel-proof-processing.rst b/doc/sphinx/addendum/parallel-proof-processing.rst new file mode 100644 index 0000000000..903ee115c9 --- /dev/null +++ b/doc/sphinx/addendum/parallel-proof-processing.rst @@ -0,0 +1,228 @@ +.. _asynchronousandparallelproofprocessing: + +Asynchronous and Parallel Proof Processing +========================================== + +:Author: Enrico Tassi + +This chapter explains how proofs can be asynchronously processed by +|Coq|. This feature improves the reactivity of the system when used in +interactive mode via |CoqIDE|. In addition, it allows |Coq| to take +advantage of parallel hardware when used as a batch compiler by +decoupling the checking of statements and definitions from the +construction and checking of proofs objects. + +This feature is designed to help dealing with huge libraries of +theorems characterized by long proofs. In the current state, it may +not be beneficial on small sets of short files. + +This feature has some technical limitations that may make it +unsuitable for some use cases. + +For example, in interactive mode, some errors coming from the kernel +of |Coq| are signaled late. The type of errors belonging to this +category are universe inconsistencies. + +At the time of writing, only opaque proofs (ending with ``Qed`` or +``Admitted``) can be processed asynchronously. + +Finally, asynchronous processing is disabled when running |CoqIDE| in +Windows. The current implementation of the feature is not stable on +Windows. It can be enabled, as described below at :ref:`interactive-mode`, +though doing so is not recommended. + +Proof annotations +---------------------- + +To process a proof asynchronously |Coq| needs to know the precise +statement of the theorem without looking at the proof. This requires +some annotations if the theorem is proved inside a Section (see +Section :ref:`section-mechanism`). + +When a section ends, |Coq| looks at the proof object to decide which +section variables are actually used and hence have to be quantified in +the statement of the theorem. To avoid making the construction of +proofs mandatory when ending a section, one can start each proof with +the ``Proof using`` command (Section :ref:`proof-editing-mode`) that +declares which section variables the theorem uses. + +The presence of ``Proof`` using is needed to process proofs asynchronously +in interactive mode. + +It is not strictly mandatory in batch mode if it is not the first time +the file is compiled and if the file itself did not change. When the +proof does not begin with Proof using, the system records in an +auxiliary file, produced along with the ``.vo`` file, the list of section +variables used. + +Automatic suggestion of proof annotations +````````````````````````````````````````` + +The flag :flag:`Suggest Proof Using` makes |Coq| suggest, when a ``Qed`` +command is processed, a correct proof annotation. It is up to the user +to modify the proof script accordingly. + + +Proof blocks and error resilience +-------------------------------------- + +|Coq| 8.6 introduced a mechanism for error resilience: in interactive +mode |Coq| is able to completely check a document containing errors +instead of bailing out at the first failure. + +Two kind of errors are supported: errors occurring in vernacular +commands and errors occurring in proofs. + +To properly recover from a failing tactic, |Coq| needs to recognize the +structure of the proof in order to confine the error to a sub proof. +Proof block detection is performed by looking at the syntax of the +proof script (i.e. also looking at indentation). |Coq| comes with four +kind of proof blocks, and an ML API to add new ones. + +:curly: blocks are delimited by { and }, see Chapter :ref:`proofhandling` +:par: blocks are atomic, i.e. just one tactic introduced by the `par:` + goal selector +:indent: blocks end with a tactic indented less than the previous one +:bullet: blocks are delimited by two equal bullet signs at the same + indentation level + +Caveats +```````` + +When a vernacular command fails the subsequent error messages may be +bogus, i.e. caused by the first error. Error resilience for vernacular +commands can be switched off by passing ``-async-proofs-command-error-resilience off`` +to |CoqIDE|. + +An incorrect proof block detection can result into an incorrect error +recovery and hence in bogus errors. Proof block detection cannot be +precise for bullets or any other non well parenthesized proof +structure. Error resilience can be turned off or selectively activated +for any set of block kind passing to |CoqIDE| one of the following +options: + +- ``-async-proofs-tactic-error-resilience off`` +- ``-async-proofs-tactic-error-resilience all`` +- ``-async-proofs-tactic-error-resilience`` :n:`{*, blocktype}` + +Valid proof block types are: “curly”, “par”, “indent”, and “bullet”. + +.. _interactive-mode: + +Interactive mode +--------------------- + +At the time of writing the only user interface supporting asynchronous +proof processing is |CoqIDE|. + +When |CoqIDE| is started, two |Coq| processes are created. The master one +follows the user, giving feedback as soon as possible by skipping +proofs, which are delegated to the worker process. The worker process, +whose state can be seen by clicking on the button in the lower right +corner of the main |CoqIDE| window, asynchronously processes the proofs. +If a proof contains an error, it is reported in red in the label of +the very same button, that can also be used to see the list of errors +and jump to the corresponding line. + +If a proof is processed asynchronously the corresponding Qed command +is colored using a lighter color than usual. This signals that the +proof has been delegated to a worker process (or will be processed +lazily if the ``-async-proofs lazy`` option is used). Once finished, the +worker process will provide the proof object, but this will not be +automatically checked by the kernel of the main process. To force the +kernel to check all the proof objects, one has to click the button +with the gears (Fully check the document) on the top bar. +Only then all the universe constraints are checked. + +Caveats +``````` + +The number of worker processes can be increased by passing |CoqIDE| +the ``-async-proofs-j n`` flag. Note that the memory consumption increases too, +since each worker requires the same amount of memory as the master +process. Also note that increasing the number of workers may reduce +the reactivity of the master process to user commands. + +To disable this feature, one can pass the ``-async-proofs off`` flag to +|CoqIDE|. Conversely, on Windows, where the feature is disabled by +default, pass the ``-async-proofs on`` flag to enable it. + +Proofs that are known to take little time to process are not delegated +to a worker process. The threshold can be configured with +``-async-proofs-delegation-threshold``. Default is 0.03 seconds. + +Batch mode +--------------- + +When |Coq| is used as a batch compiler by running ``coqc``, it produces +a ``.vo`` file for each ``.v`` file. A ``.vo`` file contains, among other +things, theorem statements and proofs. Hence to produce a .vo |Coq| +need to process all the proofs of the ``.v`` file. + +The asynchronous processing of proofs can decouple the generation of a +compiled file (like the ``.vo`` one) that can be loaded by ``Require`` from the +generation and checking of the proof objects. The ``-quick`` flag can be +passed to ``coqc`` or ``coqtop`` to produce, quickly, ``.vio`` files. +Alternatively, when using a Makefile produced by ``coq_makefile``, +the ``quick`` target can be used to compile all files using the ``-quick`` flag. + +A ``.vio`` file can be loaded using ``Require`` exactly as a ``.vo`` file but +proofs will not be available (the Print command produces an error). +Moreover, some universe constraints might be missing, so universes +inconsistencies might go unnoticed. A ``.vio`` file does not contain proof +objects, but proof tasks, i.e. what a worker process can transform +into a proof object. + +Compiling a set of files with the ``-quick`` flag allows one to work, +interactively, on any file without waiting for all the proofs to be +checked. + +When working interactively, one can fully check all the ``.v`` files by +running ``coqc`` as usual. + +Alternatively one can turn each ``.vio`` into the corresponding ``.vo``. All +.vio files can be processed in parallel, hence this alternative might +be faster. The command ``coqtop -schedule-vio2vo 2 a b c`` can be used to +obtain a good scheduling for two workers to produce ``a.vo``, ``b.vo``, and +``c.vo``. When using a Makefile produced by ``coq_makefile``, the ``vio2vo`` target +can be used for that purpose. Variable ``J`` should be set to the number +of workers, e.g. ``make vio2vo J=2``. The only caveat is that, while the +.vo files obtained from ``.vio`` files are complete (they contain all proof +terms and universe constraints), the satisfiability of all universe +constraints has not been checked globally (they are checked to be +consistent for every single proof). Constraints will be checked when +these ``.vo`` files are (recursively) loaded with ``Require``. + +There is an extra, possibly even faster, alternative: just check the +proof tasks stored in ``.vio`` files without producing the ``.vo`` files. This +is possibly faster because all the proof tasks are independent, hence +one can further partition the job to be done between workers. The +``coqtop -schedule-vio-checking 6 a b c`` command can be used to obtain a +good scheduling for 6 workers to check all the proof tasks of ``a.vio``, +``b.vio``, and ``c.vio``. Auxiliary files are used to predict how long a proof +task will take, assuming it will take the same amount of time it took +last time. When using a Makefile produced by coq_makefile, the +``checkproofs`` target can be used to check all ``.vio`` files. Variable ``J`` +should be set to the number of workers, e.g. ``make checkproofs J=6``. As +when converting ``.vio`` files to ``.vo`` files, universe constraints are not +checked to be globally consistent. Hence this compilation mode is only +useful for quick regression testing and on developments not making +heavy use of the ``Type`` hierarchy. + +Limiting the number of parallel workers +-------------------------------------------- + +Many |Coq| processes may run on the same computer, and each of them may +start many additional worker processes. The ``coqworkmgr`` utility lets +one limit the number of workers, globally. + +The utility accepts the ``-j`` argument to specify the maximum number of +workers (defaults to 2). ``coqworkmgr`` automatically starts in the +background and prints an environment variable assignment +like ``COQWORKMGR_SOCKET=localhost:45634``. The user must set this variable +in all the shells from which |Coq| processes will be started. If one +uses just one terminal running the bash shell, then +``export ‘coqworkmgr -j 4‘`` will do the job. + +After that, all |Coq| processes, e.g. ``coqide`` and ``coqc``, will respect the +limit, globally. diff --git a/doc/sphinx/addendum/program.rst b/doc/sphinx/addendum/program.rst new file mode 100644 index 0000000000..b410833d25 --- /dev/null +++ b/doc/sphinx/addendum/program.rst @@ -0,0 +1,387 @@ +.. this should be just "_program", but refs to it don't work + +.. _programs: + +Program +======== + +:Author: Matthieu Sozeau + +We present here the |Program| tactic commands, used to build +certified |Coq| programs, elaborating them from their algorithmic +skeleton and a rich specification :cite:`sozeau06`. It can be thought of as a +dual of :ref:`Extraction <extraction>`. The goal of |Program| is to +program as in a regular functional programming language whilst using +as rich a specification as desired and proving that the code meets the +specification using the whole |Coq| proof apparatus. This is done using +a technique originating from the “Predicate subtyping” mechanism of +PVS :cite:`Rushby98`, which generates type checking conditions while typing a +term constrained to a particular type. Here we insert existential +variables in the term, which must be filled with proofs to get a +complete |Coq| term. |Program| replaces the |Program| tactic by Catherine +Parent :cite:`Parent95b` which had a similar goal but is no longer maintained. + +The languages available as input are currently restricted to |Coq|’s +term language, but may be extended to OCaml, Haskell and +others in the future. We use the same syntax as |Coq| and permit to use +implicit arguments and the existing coercion mechanism. Input terms +and types are typed in an extended system (Russell) and interpreted +into |Coq| terms. The interpretation process may produce some proof +obligations which need to be resolved to create the final term. + + +.. _elaborating-programs: + +Elaborating programs +--------------------- + +The main difference from |Coq| is that an object in a type :g:`T : Set` can +be considered as an object of type :g:`{x : T | P}` for any well-formed +:g:`P : Prop`. If we go from :g:`T` to the subset of :g:`T` verifying property +:g:`P`, we must prove that the object under consideration verifies it. Russell +will generate an obligation for every such coercion. In the other direction, +Russell will automatically insert a projection. + +Another distinction is the treatment of pattern matching. Apart from +the following differences, it is equivalent to the standard match +operation (see :ref:`extendedpatternmatching`). + + ++ Generation of equalities. A match expression is always generalized + by the corresponding equality. As an example, the expression: + + :: + + match x with + | 0 => t + | S n => u + end. + + will be first rewritten to: + + :: + + (match x as y return (x = y -> _) with + | 0 => fun H : x = 0 -> t + | S n => fun H : x = S n -> u + end) (eq_refl x). + + This permits to get the proper equalities in the context of proof + obligations inside clauses, without which reasoning is very limited. + ++ Generation of disequalities. If a pattern intersects with a previous + one, a disequality is added in the context of the second branch. See + for example the definition of div2 below, where the second branch is + typed in a context where :g:`∀ p, _ <> S (S p)`. ++ Coercion. If the object being matched is coercible to an inductive + type, the corresponding coercion will be automatically inserted. This + also works with the previous mechanism. + + +There are options to control the generation of equalities and +coercions. + +.. flag:: Program Cases + + This controls the special treatment of pattern matching generating equalities + and disequalities when using |Program| (it is on by default). All + pattern-matches and let-patterns are handled using the standard algorithm + of |Coq| (see :ref:`extendedpatternmatching`) when this option is + deactivated. + +.. flag:: Program Generalized Coercion + + This controls the coercion of general inductive types when using |Program| + (the option is on by default). Coercion of subset types and pairs is still + active in this case. + +.. flag:: Program Mode + + Enables the program mode, in which 1) typechecking allows subset coercions and + 2) the elaboration of pattern matching of :cmd:`Program Fixpoint` and + :cmd:`Program Definition` act + like Program Fixpoint/Definition, generating obligations if there are + unresolved holes after typechecking. + +.. _syntactic_control: + +Syntactic control over equalities +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +To give more control over the generation of equalities, the +type checker will fall back directly to |Coq|’s usual typing of dependent +pattern matching if a ``return`` or ``in`` clause is specified. Likewise, the +if construct is not treated specially by |Program| so boolean tests in +the code are not automatically reflected in the obligations. One can +use the :g:`dec` combinator to get the correct hypotheses as in: + +.. coqtop:: in + + Require Import Program Arith. + +.. coqtop:: all + + Program Definition id (n : nat) : { x : nat | x = n } := + if dec (leb n 0) then 0 + else S (pred n). + +The :g:`let` tupling construct :g:`let (x1, ..., xn) := t in b` does not +produce an equality, contrary to the let pattern construct +:g:`let '(x1,..., xn) := t in b`. +Also, :g:`term :>` explicitly asks the system to +coerce term to its support type. It can be useful in notations, for +example: + +.. coqtop:: all + + Notation " x `= y " := (@eq _ (x :>) (y :>)) (only parsing). + +This notation denotes equality on subset types using equality on their +support types, avoiding uses of proof-irrelevance that would come up +when reasoning with equality on the subset types themselves. + +The next two commands are similar to their standard counterparts +:cmd:`Definition` and :cmd:`Fixpoint` +in that they define constants. However, they may require the user to +prove some goals to construct the final definitions. + + +.. _program_definition: + +Program Definition +~~~~~~~~~~~~~~~~~~ + +.. cmd:: Program Definition @ident := @term + + This command types the value term in Russell and generates proof + obligations. Once solved using the commands shown below, it binds the + final |Coq| term to the name ``ident`` in the environment. + + .. exn:: @ident already exists. + :name: @ident already exists. (Program Definition) + :undocumented: + + .. cmdv:: Program Definition @ident : @type := @term + + It interprets the type ``type``, potentially generating proof + obligations to be resolved. Once done with them, we have a |Coq| + type |type_0|. It then elaborates the preterm ``term`` into a |Coq| + term |term_0|, checking that the type of |term_0| is coercible to + |type_0|, and registers ``ident`` as being of type |type_0| once the + set of obligations generated during the interpretation of |term_0| + and the aforementioned coercion derivation are solved. + + .. exn:: In environment … the term: @term does not have type @type. Actually, it has type ... + :undocumented: + + .. cmdv:: Program Definition @ident @binders : @type := @term + + This is equivalent to: + + :g:`Program Definition ident : forall binders, type := fun binders => term`. + + .. TODO refer to production in alias + +.. seealso:: Sections :ref:`vernac-controlling-the-reduction-strategies`, :tacn:`unfold` + +.. _program_fixpoint: + +Program Fixpoint +~~~~~~~~~~~~~~~~ + +.. cmd:: Program Fixpoint @ident @binders {? {@order}} : @type := @term + + The optional order annotation follows the grammar: + + .. productionlist:: orderannot + order : measure `term` [ `term` ] | wf `term` `ident` + + + :g:`measure f R` where :g:`f` is a value of type :g:`X` computed on + any subset of the arguments and the optional term + :g:`R` is a relation on :g:`X`. :g:`X` defaults to :g:`nat` and :g:`R` + to :g:`lt`. + + + :g:`wf R x` which is equivalent to :g:`measure x R`. + + The structural fixpoint operator behaves just like the one of |Coq| (see + :cmd:`Fixpoint`), except it may also generate obligations. It works + with mutually recursive definitions too. + +.. coqtop:: reset in + + Require Import Program Arith. + +.. coqtop:: all + + Program Fixpoint div2 (n : nat) : { x : nat | n = 2 * x \/ n = 2 * x + 1 } := + match n with + | S (S p) => S (div2 p) + | _ => O + end. + +Here we have one obligation for each branch (branches for :g:`0` and +``(S 0)`` are automatically generated by the pattern matching +compilation algorithm). + +.. coqtop:: all + + Obligation 1. + +.. coqtop:: reset none + + Require Import Program Arith. + +One can use a well-founded order or a measure as termination orders +using the syntax: + +.. coqtop:: in + + Program Fixpoint div2 (n : nat) {measure n} : { x : nat | n = 2 * x \/ n = 2 * x + 1 } := + match n with + | S (S p) => S (div2 p) + | _ => O + end. + + + +.. caution:: When defining structurally recursive functions, the generated + obligations should have the prototype of the currently defined + functional in their context. In this case, the obligations should be + transparent (e.g. defined using :g:`Defined`) so that the guardedness + condition on recursive calls can be checked by the kernel’s type- + checker. There is an optimization in the generation of obligations + which gets rid of the hypothesis corresponding to the functional when + it is not necessary, so that the obligation can be declared opaque + (e.g. using :g:`Qed`). However, as soon as it appears in the context, the + proof of the obligation is *required* to be declared transparent. + + No such problems arise when using measures or well-founded recursion. + +.. _program_lemma: + +Program Lemma +~~~~~~~~~~~~~ + +.. cmd:: Program Lemma @ident : @type + + The Russell language can also be used to type statements of logical + properties. It will generate obligations, try to solve them + automatically and fail if some unsolved obligations remain. In this + case, one can first define the lemma’s statement using :g:`Program + Definition` and use it as the goal afterwards. Otherwise the proof + will be started with the elaborated version as a goal. The + :g:`Program` prefix can similarly be used as a prefix for + :g:`Variable`, :g:`Hypothesis`, :g:`Axiom` etc. + +.. _solving_obligations: + +Solving obligations +-------------------- + +The following commands are available to manipulate obligations. The +optional identifier is used when multiple functions have unsolved +obligations (e.g. when defining mutually recursive blocks). The +optional tactic is replaced by the default one if not specified. + +.. cmd:: {? Local|Global} Obligation Tactic := @tactic + :name: Obligation Tactic + + Sets the default obligation solving tactic applied to all obligations + automatically, whether to solve them or when starting to prove one, + e.g. using :g:`Next`. :g:`Local` makes the setting last only for the current + module. Inside sections, local is the default. + +.. cmd:: Show Obligation Tactic + + Displays the current default tactic. + +.. cmd:: Obligations {? of @ident} + + Displays all remaining obligations. + +.. cmd:: Obligation num {? of @ident} + + Start the proof of obligation num. + +.. cmd:: Next Obligation {? of @ident} + + Start the proof of the next unsolved obligation. + +.. cmd:: Solve Obligations {? {? of @ident} with @tactic} + + Tries to solve each obligation of ``ident`` using the given ``tactic`` or the default one. + +.. cmd:: Solve All Obligations {? with @tactic} + + Tries to solve each obligation of every program using the given + tactic or the default one (useful for mutually recursive definitions). + +.. cmd:: Admit Obligations {? of @ident} + + Admits all obligations (of ``ident``). + + .. note:: Does not work with structurally recursive programs. + +.. cmd:: Preterm {? of @ident} + + Shows the term that will be fed to the kernel once the obligations + are solved. Useful for debugging. + +.. flag:: Transparent Obligations + + Controls whether all obligations should be declared as transparent + (the default), or if the system should infer which obligations can be + declared opaque. + +.. flag:: Hide Obligations + + Controls whether obligations appearing in the + term should be hidden as implicit arguments of the special + constantProgram.Tactics.obligation. + +.. flag:: Shrink Obligations + + *Deprecated since 8.7* + + This option (on by default) controls whether obligations should have + their context minimized to the set of variables used in the proof of + the obligation, to avoid unnecessary dependencies. + +The module :g:`Coq.Program.Tactics` defines the default tactic for solving +obligations called :g:`program_simpl`. Importing :g:`Coq.Program.Program` also +adds some useful notations, as documented in the file itself. + +.. _program-faq: + +Frequently Asked Questions +--------------------------- + + +.. exn:: Ill-formed recursive definition. + + This error can happen when one tries to define a function by structural + recursion on a subset object, which means the |Coq| function looks like: + + :: + + Program Fixpoint f (x : A | P) := match x with A b => f b end. + + Supposing ``b : A``, the argument at the recursive call to ``f`` is not a + direct subterm of ``x`` as ``b`` is wrapped inside an ``exist`` constructor to + build an object of type ``{x : A | P}``. Hence the definition is + rejected by the guardedness condition checker. However one can use + wellfounded recursion on subset objects like this: + + :: + + Program Fixpoint f (x : A | P) { measure (size x) } := + match x with A b => f b end. + + One will then just have to prove that the measure decreases at each + recursive call. There are three drawbacks though: + + #. A measure function has to be defined; + #. The reduction is a little more involved, although it works well + using lazy evaluation; + #. Mutual recursion on the underlying inductive type isn’t possible + anymore, but nested mutual recursion is always possible. diff --git a/doc/sphinx/addendum/ring.rst b/doc/sphinx/addendum/ring.rst new file mode 100644 index 0000000000..3b350d5dc0 --- /dev/null +++ b/doc/sphinx/addendum/ring.rst @@ -0,0 +1,764 @@ +.. |ra| replace:: :math:`\rightarrow_{\beta\delta\iota}` +.. |la| replace:: :math:`\leftarrow_{\beta\delta\iota}` +.. |eq| replace:: `=`:sub:`(by the main correctness theorem)` +.. |re| replace:: ``(PEeval`` `v` `ap`\ ``)`` +.. |le| replace:: ``(Pphi_dev`` `v` ``(norm`` `ap`\ ``))`` + +.. _theringandfieldtacticfamilies: + +The ring and field tactic families +==================================== + +:Author: Bruno Barras, Benjamin Grégoire, Assia Mahboubi, Laurent Théry [#f1]_ + +This chapter presents the tactics dedicated to dealing with ring and +field equations. + +What does this tactic do? +------------------------------ + +``ring`` does associative-commutative rewriting in ring and semiring +structures. Assume you have two binary functions :math:`\oplus` and +:math:`\otimes` that are associative and commutative, with :math:`\oplus` +distributive on :math:`\otimes`, and two constants 0 and 1 that are unities for +:math:`\oplus` and :math:`\otimes`. A polynomial is an expression built on +variables :math:`V_0`, :math:`V_1`, :math:`\dots` and constants by application +of :math:`\oplus` and :math:`\otimes`. + +Let an ordered product be a product of variables :math:`V_{i_1} \otimes \dots +\otimes V_{i_n}` verifying :math:`i_1 ≤ i_2 ≤ \dots ≤ i_n` . Let a monomial be +the product of a constant and an ordered product. We can order the monomials by +the lexicographic order on products of variables. Let a canonical sum be an +ordered sum of monomials that are all different, i.e. each monomial in the sum +is strictly less than the following monomial according to the lexicographic +order. It is an easy theorem to show that every polynomial is equivalent (modulo +the ring properties) to exactly one canonical sum. This canonical sum is called +the normal form of the polynomial. In fact, the actual representation shares +monomials with same prefixes. So what does the ``ring`` tactic do? It normalizes polynomials over +any ring or semiring structure. The basic use of ``ring`` is to simplify ring +expressions, so that the user does not have to deal manually with the theorems +of associativity and commutativity. + + +.. example:: + + In the ring of integers, the normal form of + :math:`x (3 + yx + 25(1 − z)) + zx` + is + :math:`28x + (−24)xz + xxy`. + + +``ring`` is also able to compute a normal form modulo monomial equalities. +For example, under the hypothesis that :math:`2x^2 = yz+1`, the normal form of +:math:`2(x + 1)x − x − zy` is :math:`x+1`. + +The variables map +---------------------- + +It is frequent to have an expression built with :math:`+` and :math:`\times`, +but rarely on variables only. Let us associate a number to each subterm of a +ring expression in the Gallina language. For example, consider this expression +in the semiring ``nat``: + +:: + + (plus (mult (plus (f (5)) x) x) + (mult (if b then (4) else (f (3))) (2))) + + +As a ring expression, it has 3 subterms. Give each subterm a number in +an arbitrary order: + +===== =============== ========================= +0 :math:`\mapsto` if b then (4) else (f (3)) +1 :math:`\mapsto` (f (5)) +2 :math:`\mapsto` x +===== =============== ========================= + +Then normalize the “abstract” polynomial +:math:`((V_1 \otimes V_2 ) \oplus V_2) \oplus (V_0 \otimes 2)` +In our example the normal form is: +:math:`(2 \otimes V_0 ) \oplus (V_1 \otimes V_2) \oplus (V_2 \otimes V_2 )`. +Then substitute the variables by their values in the variables map to +get the concrete normal polynomial: + +:: + + (plus (mult (2) (if b then (4) else (f (3)))) + (plus (mult (f (5)) x) (mult x x))) + + +Is it automatic? +--------------------- + +Yes, building the variables map and doing the substitution after +normalizing is automatically done by the tactic. So you can just +forget this paragraph and use the tactic according to your intuition. + +Concrete usage in Coq +-------------------------- + +.. tacn:: ring + + This tactic solves equations upon polynomial expressions of a ring + (or semiring) structure. It proceeds by normalizing both sides + of the equation (w.r.t. associativity, commutativity and + distributivity, constant propagation, rewriting of monomials) and + comparing syntactically the results. + +.. tacn:: ring_simplify + + This tactic applies the normalization procedure described above to + the given terms. The tactic then replaces all occurrences of the terms + given in the conclusion of the goal by their normal forms. If no term + is given, then the conclusion should be an equation and both + sides are normalized. The tactic can also be applied in a hypothesis. + + The tactic must be loaded by ``Require Import Ring``. The ring structures + must be declared with the ``Add Ring`` command (see below). The ring of + booleans is predefined; if one wants to use the tactic on |nat| one must + first require the module ``ArithRing`` exported by ``Arith``); for |Z|, do + ``Require Import ZArithRing`` or simply ``Require Import ZArith``; for |N|, do + ``Require Import NArithRing`` or ``Require Import NArith``. + + +.. example:: + + .. coqtop:: all + + Require Import ZArith. + Open Scope Z_scope. + Goal forall a b c:Z, + (a + b + c) ^ 2 = + a * a + b ^ 2 + c * c + 2 * a * b + 2 * a * c + 2 * b * c. + intros; ring. + Abort. + Goal forall a b:Z, + 2 * a * b = 30 -> (a + b) ^ 2 = a ^ 2 + b ^ 2 + 30. + intros a b H; ring [H]. + Abort. + + +.. tacv:: ring [{* @term }] + + This tactic decides the equality of two terms modulo ring operations and + the equalities defined by the :token:`term`\ s. + Each :token:`term` has to be a proof of some equality :g:`m = p`, where :g:`m` + is a monomial (after “abstraction”), :g:`p` a polynomial and :g:`=` the + corresponding equality of the ring structure. + +.. tacv:: ring_simplify [{* @term }] {* @term } in @ident + + This tactic performs the simplification in the hypothesis named :token:`ident`. + + +.. note:: + + :n:`ring_simplify @term__1; ring_simplify @term__2` is not equivalent to + :n:`ring_simplify @term__1 @term__2`. + + In the latter case the variables map is shared between the two terms, and + common subterm :g:`t` of :n:`@term__1` and :n:`@term__2` + will have the same associated variable number. So the first + alternative should be avoided for terms belonging to the same ring + theory. + + +Error messages: + + +.. exn:: Not a valid ring equation. + + The conclusion of the goal is not provable in the corresponding ring theory. + +.. exn:: Arguments of ring_simplify do not have all the same type. + + :tacn:`ring_simplify` cannot simplify terms of several rings at the same + time. Invoke the tactic once per ring structure. + +.. exn:: Cannot find a declared ring structure over @term. + + No ring has been declared for the type of the terms to be simplified. + Use :cmd:`Add Ring` first. + +.. exn:: Cannot find a declared ring structure for equality @term. + + Same as above in the case of the :tacn:`ring` tactic. + + +Adding a ring structure +---------------------------- + +Declaring a new ring consists in proving that a ring signature (a +carrier set, an equality, and ring operations: ``Ring_theory.ring_theory`` +and ``Ring_theory.semi_ring_theory``) satisfies the ring axioms. Semi- +rings (rings without + inverse) are also supported. The equality can +be either Leibniz equality, or any relation declared as a setoid (see +:ref:`tactics-enabled-on-user-provided-relations`). +The definitions of ring and semiring (see module ``Ring_theory``) are: + +.. coqdoc:: + + Record ring_theory : Prop := mk_rt { + Radd_0_l : forall x, 0 + x == x; + Radd_sym : forall x y, x + y == y + x; + Radd_assoc : forall x y z, x + (y + z) == (x + y) + z; + Rmul_1_l : forall x, 1 * x == x; + Rmul_sym : forall x y, x * y == y * x; + Rmul_assoc : forall x y z, x * (y * z) == (x * y) * z; + Rdistr_l : forall x y z, (x + y) * z == (x * z) + (y * z); + Rsub_def : forall x y, x - y == x + -y; + Ropp_def : forall x, x + (- x) == 0 + }. + + Record semi_ring_theory : Prop := mk_srt { + SRadd_0_l : forall n, 0 + n == n; + SRadd_sym : forall n m, n + m == m + n ; + SRadd_assoc : forall n m p, n + (m + p) == (n + m) + p; + SRmul_1_l : forall n, 1*n == n; + SRmul_0_l : forall n, 0*n == 0; + SRmul_sym : forall n m, n*m == m*n; + SRmul_assoc : forall n m p, n*(m*p) == (n*m)*p; + SRdistr_l : forall n m p, (n + m)*p == n*p + m*p + }. + + +This implementation of ``ring`` also features a notion of constant that +can be parameterized. This can be used to improve the handling of +closed expressions when operations are effective. It consists in +introducing a type of *coefficients* and an implementation of the ring +operations, and a morphism from the coefficient type to the ring +carrier type. The morphism needs not be injective, nor surjective. + +As an example, one can consider the real numbers. The set of +coefficients could be the rational numbers, upon which the ring +operations can be implemented. The fact that there exists a morphism +is defined by the following properties: + +.. coqdoc:: + + Record ring_morph : Prop := mkmorph { + morph0 : [cO] == 0; + morph1 : [cI] == 1; + morph_add : forall x y, [x +! y] == [x]+[y]; + morph_sub : forall x y, [x -! y] == [x]-[y]; + morph_mul : forall x y, [x *! y] == [x]*[y]; + morph_opp : forall x, [-!x] == -[x]; + morph_eq : forall x y, x?=!y = true -> [x] == [y] + }. + + Record semi_morph : Prop := mkRmorph { + Smorph0 : [cO] == 0; + Smorph1 : [cI] == 1; + Smorph_add : forall x y, [x +! y] == [x]+[y]; + Smorph_mul : forall x y, [x *! y] == [x]*[y]; + Smorph_eq : forall x y, x?=!y = true -> [x] == [y] + }. + + +where ``c0`` and ``cI`` denote the 0 and 1 of the coefficient set, ``+!``, ``*!``, ``-!`` +are the implementations of the ring operations, ``==`` is the equality of +the coefficients, ``?+!`` is an implementation of this equality, and ``[x]`` +is a notation for the image of ``x`` by the ring morphism. + +Since |Z| is an initial ring (and |N| is an initial semiring), it can +always be considered as a set of coefficients. There are basically +three kinds of (semi-)rings: + +abstract rings + to be used when operations are not effective. The set + of coefficients is |Z| (or |N| for semirings). + +computational rings + to be used when operations are effective. The + set of coefficients is the ring itself. The user only has to provide + an implementation for the equality. + +customized ring + for other cases. The user has to provide the + coefficient set and the morphism. + + +This implementation of ring can also recognize simple power +expressions as ring expressions. A power function is specified by the +following property: + +.. coqtop:: in + + Require Import Reals. + Section POWER. + Variable Cpow : Set. + Variable Cp_phi : N -> Cpow. + Variable rpow : R -> Cpow -> R. + + Record power_theory : Prop := mkpow_th { + rpow_pow_N : forall r n, rpow r (Cp_phi n) = pow_N 1%R Rmult r n + }. + + End POWER. + + +The syntax for adding a new ring is + +.. cmd:: Add Ring @ident : @term {? ( @ring_mod {* , @ring_mod } )} + + The :token:`ident` is not relevant. It is used just for error messages. The + :token:`term` is a proof that the ring signature satisfies the (semi-)ring + axioms. The optional list of modifiers is used to tailor the behavior + of the tactic. The following list describes their syntax and effects: + + .. productionlist:: coq + ring_mod : abstract | decidable `term` | morphism `term` + : setoid `term` `term` + : constants [`ltac`] + : preprocess [`ltac`] + : postprocess [`ltac`] + : power_tac `term` [`ltac`] + : sign `term` + : div `term` + + abstract + declares the ring as abstract. This is the default. + + decidable :n:`@term` + declares the ring as computational. The expression + :n:`@term` is the correctness proof of an equality test ``?=!`` + (which should be evaluable). Its type should be of the form + ``forall x y, x ?=! y = true → x == y``. + + morphism :n:`@term` + declares the ring as a customized one. The expression + :n:`@term` is a proof that there exists a morphism between a set of + coefficient and the ring carrier (see ``Ring_theory.ring_morph`` and + ``Ring_theory.semi_morph``). + + setoid :n:`@term` :n:`@term` + forces the use of given setoid. The first + :n:`@term` is a proof that the equality is indeed a setoid (see + ``Setoid.Setoid_Theory``), and the second :n:`@term` a proof that the + ring operations are morphisms (see ``Ring_theory.ring_eq_ext`` and + ``Ring_theory.sring_eq_ext``). + This modifier needs not be used if the setoid and morphisms have been + declared. + + constants [ :n:`@ltac` ] + specifies a tactic expression :n:`@ltac` that, given a + term, returns either an object of the coefficient set that is mapped + to the expression via the morphism, or returns + ``InitialRing.NotConstant``. The default behavior is to map only 0 and 1 + to their counterpart in the coefficient set. This is generally not + desirable for non trivial computational rings. + + preprocess [ :n:`@ltac` ] + specifies a tactic :n:`@ltac` that is applied as a + preliminary step for :tacn:`ring` and :tacn:`ring_simplify`. It can be used to + transform a goal so that it is better recognized. For instance, ``S n`` + can be changed to ``plus 1 n``. + + postprocess [ :n:`@ltac` ] + specifies a tactic :n:`@ltac` that is applied as a final + step for :tacn:`ring_simplify`. For instance, it can be used to undo + modifications of the preprocessor. + + power_tac :n:`@term` [ :n:`@ltac` ] + allows :tacn:`ring` and :tacn:`ring_simplify` to recognize + power expressions with a constant positive integer exponent (example: + :math:`x^2` ). The term :n:`@term` is a proof that a given power function satisfies + the specification of a power function (term has to be a proof of + ``Ring_theory.power_theory``) and :n:`@ltac` specifies a tactic expression + that, given a term, “abstracts” it into an object of type |N| whose + interpretation via ``Cp_phi`` (the evaluation function of power + coefficient) is the original term, or returns ``InitialRing.NotConstant`` + if not a constant coefficient (i.e. |L_tac| is the inverse function of + ``Cp_phi``). See files ``plugins/setoid_ring/ZArithRing.v`` + and ``plugins/setoid_ring/RealField.v`` for examples. By default the tactic + does not recognize power expressions as ring expressions. + + sign :n:`@term` + allows :tacn:`ring_simplify` to use a minus operation when + outputting its normal form, i.e writing ``x − y`` instead of ``x + (− y)``. The + term :token:`term` is a proof that a given sign function indicates expressions + that are signed (:token:`term` has to be a proof of ``Ring_theory.get_sign``). See + ``plugins/setoid_ring/InitialRing.v`` for examples of sign function. + + div :n:`@term` + allows :tacn:`ring` and :tacn:`ring_simplify` to use monomials with + coefficients other than 1 in the rewriting. The term :n:`@term` is a proof + that a given division function satisfies the specification of an + euclidean division function (:n:`@term` has to be a proof of + ``Ring_theory.div_theory``). For example, this function is called when + trying to rewrite :math:`7x` by :math:`2x = z` to tell that :math:`7 = 3 \times 2 + 1`. See + ``plugins/setoid_ring/InitialRing.v`` for examples of div function. + +Error messages: + +.. exn:: Bad ring structure. + + The proof of the ring structure provided is not + of the expected type. + +.. exn:: Bad lemma for decidability of equality. + + The equality function + provided in the case of a computational ring has not the expected + type. + +.. exn:: Ring operation should be declared as a morphism. + + A setoid associated to the carrier of the ring structure has been found, + but the ring operation should be declared as morphism. See :ref:`tactics-enabled-on-user-provided-relations`. + +How does it work? +---------------------- + +The code of ``ring`` is a good example of a tactic written using *reflection*. +What is reflection? Basically, using it means that a part of a tactic is written +in Gallina, Coq's language of terms, rather than |Ltac| or |OCaml|. From the +philosophical point of view, reflection is using the ability of the Calculus of +Constructions to speak and reason about itself. For the ``ring`` tactic we used +Coq as a programming language and also as a proof environment to build a tactic +and to prove its correctness. + +The interested reader is strongly advised to have a look at the +file ``Ring_polynom.v``. Here a type for polynomials is defined: + + +.. coqdoc:: + + Inductive PExpr : Type := + | PEc : C -> PExpr + | PEX : positive -> PExpr + | PEadd : PExpr -> PExpr -> PExpr + | PEsub : PExpr -> PExpr -> PExpr + | PEmul : PExpr -> PExpr -> PExpr + | PEopp : PExpr -> PExpr + | PEpow : PExpr -> N -> PExpr. + + +Polynomials in normal form are defined as: + + +.. coqdoc:: + + Inductive Pol : Type := + | Pc : C -> Pol + | Pinj : positive -> Pol -> Pol + | PX : Pol -> positive -> Pol -> Pol. + + +where ``Pinj n P`` denotes ``P`` in which :math:`V_i` is replaced by :math:`V_{i+n}` , +and ``PX P n Q`` denotes :math:`P \otimes V_1^n \oplus Q'`, `Q'` being `Q` where :math:`V_i` is replaced by :math:`V_{i+1}`. + +Variable maps are represented by lists of ring elements, and two +interpretation functions, one that maps a variables map and a +polynomial to an element of the concrete ring, and the second one that +does the same for normal forms: + + +.. coqdoc:: + + + Definition PEeval : list R -> PExpr -> R := [...]. + Definition Pphi_dev : list R -> Pol -> R := [...]. + + +A function to normalize polynomials is defined, and the big theorem is +its correctness w.r.t interpretation, that is: + + +.. coqdoc:: + + Definition norm : PExpr -> Pol := [...]. + Lemma Pphi_dev_ok : + forall l pe npe, norm pe = npe -> PEeval l pe == Pphi_dev l npe. + + +So now, what is the scheme for a normalization proof? Let p be the +polynomial expression that the user wants to normalize. First a little +piece of |ML| code guesses the type of `p`, the ring theory `T` to use, an +abstract polynomial `ap` and a variables map `v` such that `p` is |bdi|- +equivalent to `(PEeval v ap)`. Then we replace it by `(Pphi_dev v (norm ap))`, +using the main correctness theorem and we reduce it to a +concrete expression `p’`, which is the concrete normal form of `p`. This is summarized in this diagram: + +========= ====== ==== +`p` |ra| |re| +\ |eq| \ +`p’` |la| |le| +========= ====== ==== + +The user does not see the right part of the diagram. From outside, the +tactic behaves like a |bdi| simplification extended with rewriting rules +for associativity and commutativity. Basically, the proof is only the +application of the main correctness theorem to well-chosen arguments. + +Dealing with fields +------------------------ + +.. tacn:: field + + This tactic is an extension of the :tacn:`ring` tactic that deals with rational + expressions. Given a rational expression :math:`F = 0`. It first reduces the + expression `F` to a common denominator :math:`N/D = 0` where `N` and `D` + are two ring expressions. For example, if we take :math:`F = (1 − 1/x) x − x + 1`, this + gives :math:`N = (x − 1) x − x^2 + x` and :math:`D = x`. It then calls ring to solve + :math:`N = 0`. + + Note that :n:`field` also generates nonzero conditions for all the + denominators it encounters in the reduction. In our example, it + generates the condition :math:`x \neq 0`. These conditions appear as one subgoal + which is a conjunction if there are several denominators. Nonzero + conditions are always polynomial expressions. For example when + reducing the expression :math:`1/(1 + 1/x)`, two side conditions are + generated: :math:`x \neq 0` and :math:`x + 1 \neq 0`. Factorized expressions are broken since + a field is an integral domain, and when the equality test on + coefficients is complete w.r.t. the equality of the target field, + constants can be proven different from zero automatically. + + The tactic must be loaded by ``Require Import Field``. New field + structures can be declared to the system with the ``Add Field`` command + (see below). The field of real numbers is defined in module ``RealField`` + (in ``plugins/setoid_ring``). It is exported by module ``Rbase``, so + that requiring ``Rbase`` or ``Reals`` is enough to use the field tactics on + real numbers. Rational numbers in canonical form are also declared as + a field in the module ``Qcanon``. + + +.. example:: + + .. coqtop:: all + + Require Import Reals. + Open Scope R_scope. + Goal forall x, + x <> 0 -> (1 - 1 / x) * x - x + 1 = 0. + intros; field; auto. + Abort. + Goal forall x y, + y <> 0 -> y = x -> x / y = 1. + intros x y H H1; field [H1]; auto. + Abort. + +.. tacv:: field [{* @term}] + + This tactic decides the equality of two terms modulo + field operations and the equalities defined + by the :token:`term`\s. Each :token:`term` has to be a proof of some equality + :g:`m = p`, where :g:`m` is a monomial (after “abstraction”), :g:`p` a polynomial + and :g:`=` the corresponding equality of the field structure. + +.. note:: + + Rewriting works with the equality :g:`m = p` only if :g:`p` is a polynomial since + rewriting is handled by the underlying ring tactic. + +.. tacv:: field_simplify + + performs the simplification in the conclusion of the + goal, :math:`F_1 = F_2` becomes :math:`N_1 / D_1 = N_2 / D_2`. A normalization step + (the same as the one for rings) is then applied to :math:`N_1`, :math:`D_1`, + :math:`N_2` and :math:`D_2`. This way, polynomials remain in factorized form during + fraction simplification. This yields smaller expressions when + reducing to the same denominator since common factors can be canceled. + +.. tacv:: field_simplify [{* @term }] + + This variant performs the simplification in the conclusion of the goal using the equalities + defined by the :token:`term`\s. + +.. tacv:: field_simplify [{* @term }] {* @term } + + This variant performs the simplification in the terms :token:`term`\s of the conclusion of the goal + using the equalities defined by :token:`term`\s inside the brackets. + +.. tacv:: field_simplify in @ident + + This variant performs the simplification in the assumption :token:`ident`. + +.. tacv:: field_simplify [{* @term }] in @ident + + This variant performs the simplification + in the assumption :token:`ident` using the equalities defined by the :token:`term`\s. + +.. tacv:: field_simplify [{* @term }] {* @term } in @ident + + This variant performs the simplification in the :token:`term`\s of the + assumption :token:`ident` using the + equalities defined by the :token:`term`\s inside the brackets. + +.. tacv:: field_simplify_eq + + performs the simplification in the conclusion of + the goal removing the denominator. :math:`F_1 = F_2` becomes :math:`N_1 D_2 = N_2 D_1`. + +.. tacv:: field_simplify_eq [ {* @term }] + + This variant performs the simplification in + the conclusion of the goal using the equalities defined by :token:`term`\s. + +.. tacv:: field_simplify_eq in @ident + + This variant performs the simplification in the assumption :token:`ident`. + +.. tacv:: field_simplify_eq [{* @term}] in @ident + + This variant performs the simplification in the assumption :token:`ident` + using the equalities defined by :token:`term`\s and removing the denominator. + + +Adding a new field structure +--------------------------------- + +Declaring a new field consists in proving that a field signature (a +carrier set, an equality, and field operations: +``Field_theory.field_theory`` and ``Field_theory.semi_field_theory``) +satisfies the field axioms. Semi-fields (fields without + inverse) are +also supported. The equality can be either Leibniz equality, or any +relation declared as a setoid (see :ref:`tactics-enabled-on-user-provided-relations`). The definition of +fields and semifields is: + +.. coqdoc:: + + Record field_theory : Prop := mk_field { + F_R : ring_theory rO rI radd rmul rsub ropp req; + F_1_neq_0 : ~ 1 == 0; + Fdiv_def : forall p q, p / q == p * / q; + Finv_l : forall p, ~ p == 0 -> / p * p == 1 + }. + + Record semi_field_theory : Prop := mk_sfield { + SF_SR : semi_ring_theory rO rI radd rmul req; + SF_1_neq_0 : ~ 1 == 0; + SFdiv_def : forall p q, p / q == p * / q; + SFinv_l : forall p, ~ p == 0 -> / p * p == 1 + }. + + +The result of the normalization process is a fraction represented by +the following type: + +.. coqdoc:: + + Record linear : Type := mk_linear { + num : PExpr C; + denum : PExpr C; + condition : list (PExpr C) + }. + + +where ``num`` and ``denum`` are the numerator and denominator; ``condition`` is a +list of expressions that have appeared as a denominator during the +normalization process. These expressions must be proven different from +zero for the correctness of the algorithm. + +The syntax for adding a new field is + +.. cmd:: Add Field @ident : @term {? ( @field_mod {* , @field_mod } )} + + The :n:`@ident` is not relevant. It is used just for error + messages. :n:`@term` is a proof that the field signature satisfies the + (semi-)field axioms. The optional list of modifiers is used to tailor + the behavior of the tactic. + + .. productionlist:: coq + field_mod : `ring_mod` | completeness `term` + + Since field tactics are built upon ``ring`` + tactics, all modifiers of the ``Add Ring`` apply. There is only one + specific modifier: + + completeness :n:`@term` + allows the field tactic to prove automatically + that the image of nonzero coefficients are mapped to nonzero + elements of the field. :n:`@term` is a proof of + :g:`forall x y, [x] == [y] -> x ?=! y = true`, + which is the completeness of equality on coefficients + w.r.t. the field equality. + + +History of ring +-------------------- + +First Samuel Boutin designed the tactic ``ACDSimpl``. This tactic did lot +of rewriting. But the proofs terms generated by rewriting were too big +for |Coq|’s type checker. Let us see why: + +.. coqtop:: all + + Require Import ZArith. + Open Scope Z_scope. + Goal forall x y z : Z, + x + 3 + y + y * z = x + 3 + y + z * y. + intros; rewrite (Zmult_comm y z); reflexivity. + Save foo. + Print foo. + +At each step of rewriting, the whole context is duplicated in the +proof term. Then, a tactic that does hundreds of rewriting generates +huge proof terms. Since ``ACDSimpl`` was too slow, Samuel Boutin rewrote +it using reflection (see :cite:`Bou97`). Later, it +was rewritten by Patrick Loiseleur: the new tactic does not any +more require ``ACDSimpl`` to compile and it makes use of |bdi|-reduction not +only to replace the rewriting steps, but also to achieve the +interleaving of computation and reasoning (see :ref:`discussion_reflection`). He also wrote +some |ML| code for the ``Add Ring`` command that allows registering new rings dynamically. + +Proofs terms generated by ring are quite small, they are linear in the +number of :math:`\oplus` and :math:`\otimes` operations in the normalized terms. Type checking +those terms requires some time because it makes a large use of the +conversion rule, but memory requirements are much smaller. + + +.. _discussion_reflection: + + +Discussion +---------------- + + +Efficiency is not the only motivation to use reflection here. ``ring`` +also deals with constants, it rewrites for example the expression +``34 + 2 * x − x + 12`` to the expected result ``x + 46``. +For the tactic ``ACDSimpl``, the only constants were 0 and 1. +So the expression ``34 + 2 * (x − 1) + 12`` +is interpreted as :math:`V_0 \oplus V_1 \otimes (V_2 \ominus 1) \oplus V_3`\ , +with the variables mapping +:math:`\{V_0 \mapsto 34; V_1 \mapsto 2; V_2 \mapsto x; V_3 \mapsto 12\}`\ . +Then it is rewritten to ``34 − x + 2 * x + 12``, very far from the expected result. +Here rewriting is not sufficient: you have to do some kind of reduction +(some kind of computation) to achieve the normalization. + +The tactic ``ring`` is not only faster than the old one: by using +reflection, we get for free the integration of computation and reasoning +that would be very difficult to implement without it. + +Is it the ultimate way to write tactics? The answer is: yes and no. +The ``ring`` tactic intensively uses the conversion rules of the Calculus of +Inductive Constructions, i.e. it replaces proofs by computations as much as possible. +It can be useful in all situations where a classical tactic generates huge proof +terms, like symbolic processing and tautologies. But there +are also tactics like ``auto`` or ``linear`` that do many complex computations, +using side-effects and backtracking, and generate a small proof term. +Clearly, it would be significantly less efficient to replace them by +tactics using reflection. + +Another idea suggested by Benjamin Werner: reflection could be used to +couple an external tool (a rewriting program or a model checker) +with |Coq|. We define (in |Coq|) a type of terms, a type of *traces*, and +prove a correctness theorem that states that *replaying traces* is safe +with respect to some interpretation. Then we let the external tool do every +computation (using side-effects, backtracking, exception, or others +features that are not available in pure lambda calculus) to produce +the trace. Now we can check in |Coq| that the trace has the expected +semantics by applying the correctness theorem. + + + + + + +.. rubric:: Footnotes +.. [#f1] based on previous work from Patrick Loiseleur and Samuel Boutin + + + diff --git a/doc/sphinx/addendum/sprop.rst b/doc/sphinx/addendum/sprop.rst new file mode 100644 index 0000000000..c0c8c2d79c --- /dev/null +++ b/doc/sphinx/addendum/sprop.rst @@ -0,0 +1,239 @@ +.. _sprop: + +SProp (proof irrelevant propositions) +===================================== + +.. warning:: + + The status of strict propositions is experimental. + +This section describes the extension of |Coq| with definitionally +proof irrelevant propositions (types in the sort :math:`\SProp`, also +known as strict propositions). To use :math:`\SProp` you must pass +``-allow-sprop`` to the |Coq| program or use :opt:`Allow StrictProp`. + +.. opt:: Allow StrictProp + :name: Allow StrictProp + + Allows using :math:`\SProp` when set and forbids it when unset. The + initial value depends on whether you used the command line + ``-allow-sprop``. + +.. exn:: SProp not allowed, you need to Set Allow StrictProp or to use the -allow-sprop command-line-flag. + :undocumented: + +.. coqtop:: none + + Set Allow StrictProp. + +Some of the definitions described in this document are available +through ``Coq.Logic.StrictProp``, which see. + +Basic constructs +---------------- + +The purpose of :math:`\SProp` is to provide types where all elements +are convertible: + +.. coqdoc:: + + Definition irrelevance (A:SProp) (P:A -> Prop) (x:A) (v:P x) (y:A) : P y := v. + +Since we have definitional :ref:`eta-expansion` for +functions, the property of being a type of definitionally irrelevant +values is impredicative, and so is :math:`\SProp`: + +.. coqdoc:: + + Check fun (A:Type) (B:A -> SProp) => (forall x:A, B x) : SProp. + +.. warning:: + + Conversion checking through bytecode or native code compilation + currently does not understand proof irrelevance. + +In order to keep conversion tractable, cumulativity for :math:`\SProp` +is forbidden: + +.. coqtop:: all + + Fail Check (fun (A:SProp) => A : Type). + +We can explicitly lift strict propositions into the relevant world by +using a wrapping inductive type. The inductive stops definitional +proof irrelevance from escaping. + +.. coqtop:: in + + Inductive Box (A:SProp) : Prop := box : A -> Box A. + Arguments box {_} _. + +.. coqtop:: all + + Fail Check fun (A:SProp) (x y : Box A) => eq_refl : x = y. + +.. doesn't get merged with the above if coqdoc +.. coqtop:: in + + Definition box_irrelevant (A:SProp) (x y : Box A) : x = y + := match x, y with box x, box y => eq_refl end. + +In the other direction, we can use impredicativity to "squash" a +relevant type, making an irrelevant approximation. + +.. coqdoc:: + + Definition iSquash (A:Type) : SProp + := forall P : SProp, (A -> P) -> P. + Definition isquash A : A -> iSquash A + := fun a P f => f a. + Definition iSquash_sind A (P : iSquash A -> SProp) (H : forall x : A, P (isquash A x)) + : forall x : iSquash A, P x + := fun x => x (P x) (H : A -> P x). + +Or more conveniently (but equivalently) + +.. coqdoc:: + + Inductive Squash (A:Type) : SProp := squash : A -> Squash A. + +Most inductives types defined in :math:`\SProp` are squashed types, +i.e. they can only be eliminated to construct proofs of other strict +propositions. Empty types are the only exception. + +.. coqtop:: in + + Inductive sEmpty : SProp := . + +.. coqtop:: all + + Check sEmpty_rect. + +.. note:: + + Eliminators to strict propositions are called ``foo_sind``, in the + same way that eliminators to propositions are called ``foo_ind``. + +Primitive records in :math:`\SProp` are allowed when fields are strict +propositions, for instance: + +.. coqtop:: in + + Set Primitive Projections. + Record sProd (A B : SProp) : SProp := { sfst : A; ssnd : B }. + +On the other hand, to avoid having definitionally irrelevant types in +non-:math:`\SProp` sorts (through record η-extensionality), primitive +records in relevant sorts must have at least one relevant field. + +.. coqtop:: all + + Set Warnings "+non-primitive-record". + Fail Record rBox (A:SProp) : Prop := rbox { runbox : A }. + +.. coqdoc:: + + Record ssig (A:Type) (P:A -> SProp) : Type := { spr1 : A; spr2 : P spr1 }. + +Note that ``rBox`` works as an emulated record, which is equivalent to +the Box inductive. + +Encodings for strict propositions +--------------------------------- + +The elimination for unit types can be encoded by a trivial function +thanks to proof irrelevance: + +.. coqdoc:: + + Inductive sUnit : SProp := stt. + Definition sUnit_rect (P:sUnit->Type) (v:P stt) (x:sUnit) : P x := v. + +By using empty and unit types as base values, we can encode other +strict propositions. For instance: + +.. coqdoc:: + + Definition is_true (b:bool) : SProp := if b then sUnit else sEmpty. + + Definition is_true_eq_true b : is_true b -> true = b + := match b with + | true => fun _ => eq_refl + | false => sEmpty_ind _ + end. + + Definition eq_true_is_true b (H:true=b) : is_true b + := match H in _ = x return is_true x with eq_refl => stt end. + +Issues with non-cumulativity +---------------------------- + +During normal term elaboration, we don't always know that a type is a +strict proposition early enough. For instance: + +.. coqdoc:: + + Definition constant_0 : ?[T] -> nat := fun _ : sUnit => 0. + +While checking the type of the constant, we only know that ``?[T]`` +must inhabit some sort. Putting it in some floating universe ``u`` +would disallow instantiating it by ``sUnit : SProp``. + +In order to make the system usable without having to annotate every +instance of :math:`\SProp`, we consider :math:`\SProp` to be a subtype +of every universe during elaboration (i.e. outside the kernel). Then +once we have a fully elaborated term it is sent to the kernel which +will check that we didn't actually need cumulativity of :math:`\SProp` +(in the example above, ``u`` doesn't appear in the final term). + +This means that some errors will be delayed until ``Qed``: + +.. coqtop:: in + + Lemma foo : Prop. + Proof. pose (fun A : SProp => A : Type); exact True. + +.. coqtop:: all + + Fail Qed. + +.. coqtop:: in + + Abort. + +.. opt:: Elaboration StrictProp Cumulativity + :name: Elaboration StrictProp Cumulativity + + Unset this option (it's on by default) to be strict with regard to + :math:`\SProp` cumulativity during elaboration. + +The implementation of proof irrelevance uses inferred "relevance" +marks on binders to determine which variables are irrelevant. Together +with non-cumulativity this allows us to avoid retyping during +conversion. However during elaboration cumulativity is allowed and so +the algorithm may miss some irrelevance: + +.. coqtop:: all + + Fail Definition late_mark := fun (A:SProp) (P:A -> Prop) x y (v:P x) => v : P y. + +The binders for ``x`` and ``y`` are created before their type is known +to be ``A``, so they're not marked irrelevant. This can be avoided +with sufficient annotation of binders (see ``irrelevance`` at the +beginning of this chapter) or by bypassing the conversion check in +tactics. + +.. coqdoc:: + + Definition late_mark := fun (A:SProp) (P:A -> Prop) x y (v:P x) => + ltac:(exact_no_check v) : P y. + +The kernel will re-infer the marks on the fully elaborated term, and +so correctly converts ``x`` and ``y``. + +.. warn:: Bad relevance + + This is a developer warning, disabled by default. It is emitted by + the kernel when it is passed a term with incorrect relevance marks. + To avoid conversion issues as in ``late_mark`` you may wish to use + it to find when your tactics are producing incorrect marks. diff --git a/doc/sphinx/addendum/type-classes.rst b/doc/sphinx/addendum/type-classes.rst new file mode 100644 index 0000000000..b069cf27f4 --- /dev/null +++ b/doc/sphinx/addendum/type-classes.rst @@ -0,0 +1,593 @@ +.. _typeclasses: + +Typeclasses +=========== + +This chapter presents a quick reference of the commands related to type +classes. For an actual introduction to typeclasses, there is a +description of the system :cite:`sozeau08` and the literature on type +classes in Haskell which also applies. + + +Class and Instance declarations +------------------------------- + +The syntax for class and instance declarations is the same as the record +syntax of Coq: + +.. coqdoc:: + + Class classname (p1 : t1) ⋯ (pn : tn) [: sort] := { f1 : u1 ; ⋯ ; fm : um }. + + Instance instancename q1 ⋯ qm : classname p1 ⋯ pn := { f1 := t1 ; ⋯ ; fm := tm }. + +The ``pi : ti`` variables are called the *parameters* of the class and +the ``fi : ti`` are called the *methods*. Each class definition gives +rise to a corresponding record declaration and each instance is a +regular definition whose name is given by `instancename` and type is an +instantiation of the record type. + +We’ll use the following example class in the rest of the chapter: + +.. coqtop:: in + + Class EqDec (A : Type) := + { eqb : A -> A -> bool ; + eqb_leibniz : forall x y, eqb x y = true -> x = y }. + +This class implements a boolean equality test which is compatible with +Leibniz equality on some type. An example implementation is: + +.. coqtop:: in + + Instance unit_EqDec : EqDec unit := + { eqb x y := true ; + eqb_leibniz x y H := + match x, y return x = y with + | tt, tt => eq_refl tt + end }. + +Using :cmd:`Program Instance`, if one does not give all the members in +the Instance declaration, Coq generates obligations for the remaining +fields, e.g.: + +.. coqtop:: in + + Require Import Program.Tactics. + Program Instance eq_bool : EqDec bool := + { eqb x y := if x then y else negb y }. + +.. coqtop:: all + + Next Obligation. + destruct x ; destruct y ; (discriminate || reflexivity). + Defined. + +One has to take care that the transparency of every field is +determined by the transparency of the :cmd:`Instance` proof. One can use +alternatively the :cmd:`Program Instance` variant which has richer facilities +for dealing with obligations. + + +Binding classes +--------------- + +Once a typeclass is declared, one can use it in class binders: + +.. coqtop:: all + + Definition neqb {A} {eqa : EqDec A} (x y : A) := negb (eqb x y). + +When one calls a class method, a constraint is generated that is +satisfied only in contexts where the appropriate instances can be +found. In the example above, a constraint ``EqDec A`` is generated and +satisfied by ``eqa : EqDec A``. In case no satisfying constraint can be +found, an error is raised: + +.. coqtop:: all + + Fail Definition neqb' (A : Type) (x y : A) := negb (eqb x y). + +The algorithm used to solve constraints is a variant of the :tacn:`eauto` +tactic that does proof search with a set of lemmas (the instances). It +will use local hypotheses as well as declared lemmas in +the ``typeclass_instances`` database. Hence the example can also be +written: + +.. coqtop:: all + + Definition neqb' A (eqa : EqDec A) (x y : A) := negb (eqb x y). + +However, the generalizing binders should be used instead as they have +particular support for typeclasses: + ++ They automatically set the maximally implicit status for typeclass + arguments, making derived functions as easy to use as class methods. + In the example above, ``A`` and ``eqa`` should be set maximally implicit. ++ They support implicit quantification on partially applied type + classes (:ref:`implicit-generalization`). Any argument not given as part of a typeclass + binder will be automatically generalized. ++ They also support implicit quantification on :ref:`superclasses`. + + +Following the previous example, one can write: + +.. coqtop:: all + + Generalizable Variables A B C. + + Definition neqb_implicit `{eqa : EqDec A} (x y : A) := negb (eqb x y). + +Here ``A`` is implicitly generalized, and the resulting function is +equivalent to the one above. + +Parameterized Instances +----------------------- + +One can declare parameterized instances as in Haskell simply by giving +the constraints as a binding context before the instance, e.g.: + +.. coqtop:: in + + Program Instance prod_eqb `(EA : EqDec A, EB : EqDec B) : EqDec (A * B) := + { eqb x y := match x, y with + | (la, ra), (lb, rb) => andb (eqb la lb) (eqb ra rb) + end }. + +.. coqtop:: none + + Admit Obligations. + +These instances are used just as well as lemmas in the instance hint +database. + +.. _contexts: + +Sections and contexts +--------------------- + +To ease developments parameterized by many instances, one can use the +:cmd:`Context` command to introduce these parameters into section contexts, +it works similarly to the command :cmd:`Variable`, except it accepts any +binding context as an argument, so variables can be implicit, and +:ref:`implicit-generalization` can be used. +For example: + +.. coqtop:: all + + Section EqDec_defs. + + Context `{EA : EqDec A}. + +.. coqtop:: in + + Global Program Instance option_eqb : EqDec (option A) := + { eqb x y := match x, y with + | Some x, Some y => eqb x y + | None, None => true + | _, _ => false + end }. + Admit Obligations. + +.. coqtop:: all + + End EqDec_defs. + + About option_eqb. + +Here the :cmd:`Global` modifier redeclares the instance at the end of the +section, once it has been generalized by the context variables it +uses. + +.. seealso:: Section :ref:`section-mechanism` + +Building hierarchies +-------------------- + +.. _superclasses: + +Superclasses +~~~~~~~~~~~~ + +One can also parameterize classes by other classes, generating a +hierarchy of classes and superclasses. In the same way, we give the +superclasses as a binding context: + +.. coqtop:: all + + Class Ord `(E : EqDec A) := { le : A -> A -> bool }. + +Contrary to Haskell, we have no special syntax for superclasses, but +this declaration is equivalent to: + +.. coqdoc:: + + Class `(E : EqDec A) => Ord A := + { le : A -> A -> bool }. + + +This declaration means that any instance of the ``Ord`` class must have +an instance of ``EqDec``. The parameters of the subclass contain at +least all the parameters of its superclasses in their order of +appearance (here A is the only one). As we have seen, ``Ord`` is encoded +as a record type with two parameters: a type ``A`` and an ``E`` of type +``EqDec A``. However, one can still use it as if it had a single +parameter inside generalizing binders: the generalization of +superclasses will be done automatically. + +.. coqtop:: all + + Definition le_eqb `{Ord A} (x y : A) := andb (le x y) (le y x). + +In some cases, to be able to specify sharing of structures, one may +want to give explicitly the superclasses. It is is possible to do it +directly in regular binders, and using the ``!`` modifier in class +binders. For example: + +.. coqtop:: all + + Definition lt `{eqa : EqDec A, ! Ord eqa} (x y : A) := andb (le x y) (neqb x y). + +The ``!`` modifier switches the way a binder is parsed back to the regular +interpretation of Coq. In particular, it uses the implicit arguments +mechanism if available, as shown in the example. + +Substructures +~~~~~~~~~~~~~ + +.. index:: :> (substructure) + +Substructures are components of a class which are instances of a class +themselves. They often arise when using classes for logical +properties, e.g.: + +.. coqtop:: none + + Require Import Relation_Definitions. + +.. coqtop:: in + + Class Reflexive (A : Type) (R : relation A) := + reflexivity : forall x, R x x. + + Class Transitive (A : Type) (R : relation A) := + transitivity : forall x y z, R x y -> R y z -> R x z. + +This declares singleton classes for reflexive and transitive relations, +(see the :ref:`singleton class <singleton-class>` variant for an +explanation). These may be used as parts of other classes: + +.. coqtop:: all + + Class PreOrder (A : Type) (R : relation A) := + { PreOrder_Reflexive :> Reflexive A R ; + PreOrder_Transitive :> Transitive A R }. + +The syntax ``:>`` indicates that each ``PreOrder`` can be seen as a +``Reflexive`` relation. So each time a reflexive relation is needed, a +preorder can be used instead. This is very similar to the coercion +mechanism of ``Structure`` declarations. The implementation simply +declares each projection as an instance. + +.. warn:: Ignored instance declaration for “@ident”: “@term” is not a class + + Using this ``:>`` syntax with a right-hand-side that is not itself a Class + has no effect (apart from emitting this warning). In particular, is does not + declare a coercion. + +One can also declare existing objects or structure projections using +the Existing Instance command to achieve the same effect. + + +Summary of the commands +----------------------- + +.. cmd:: Class @ident {? @binders} : {? @sort} := {? @ident} { {+; @ident :{? >} @term } } + + The :cmd:`Class` command is used to declare a typeclass with parameters + :token:`binders` and fields the declared record fields. + + .. _singleton-class: + + .. cmdv:: Class @ident {? @binders} : {? @sort} := @ident : @term + + This variant declares a *singleton* class with a single method. This + singleton class is a so-called definitional class, represented simply + as a definition ``ident binders := term`` and whose instances are + themselves objects of this type. Definitional classes are not wrapped + inside records, and the trivial projection of an instance of such a + class is convertible to the instance itself. This can be useful to + make instances of existing objects easily and to reduce proof size by + not inserting useless projections. The class constant itself is + declared rigid during resolution so that the class abstraction is + maintained. + + .. cmdv:: Existing Class @ident + + This variant declares a class a posteriori from a constant or + inductive definition. No methods or instances are defined. + + .. warn:: @ident is already declared as a typeclass + + This command has no effect when used on a typeclass. + +.. cmd:: Instance @ident {? @binders} : @class t1 … tn [| priority] := { field1 := b1 ; …; fieldi := bi } + + This command is used to declare a typeclass instance named + :token:`ident` of the class :token:`class` with parameters ``t1`` to ``tn`` and + fields ``b1`` to ``bi``, where each field must be a declared field of + the class. Missing fields must be filled in interactive proof mode. + + An arbitrary context of :token:`binders` can be put after the name of the + instance and before the colon to declare a parameterized instance. An + optional priority can be declared, 0 being the highest priority as for + :tacn:`auto` hints. If the priority is not specified, it defaults to the number + of non-dependent binders of the instance. + + .. cmdv:: Instance @ident {? @binders} : forall {? @binders}, @class @term__1 … @term__n [| priority] := @term + + This syntax is used for declaration of singleton class instances or + for directly giving an explicit term of type :n:`forall @binders, @class + @term__1 … @term__n`. One need not even mention the unique field name for + singleton classes. + + .. cmdv:: Global Instance + :name: Global Instance + + One can use the :cmd:`Global` modifier on instances declared in a + section so that their generalization is automatically redeclared + after the section is closed. + + .. cmdv:: Program Instance + :name: Program Instance + + Switches the type checking to `Program` (chapter :ref:`programs`) and + uses the obligation mechanism to manage missing fields. + + .. cmdv:: Declare Instance + :name: Declare Instance + + In a :cmd:`Module Type`, this command states that a corresponding concrete + instance should exist in any implementation of this :cmd:`Module Type`. This + is similar to the distinction between :cmd:`Parameter` vs. :cmd:`Definition`, or + between :cmd:`Declare Module` and :cmd:`Module`. + + +Besides the :cmd:`Class` and :cmd:`Instance` vernacular commands, there are a +few other commands related to typeclasses. + +.. cmd:: Existing Instance {+ @ident} [| priority] + + This command adds an arbitrary list of constants whose type ends with + an applied typeclass to the instance database with an optional + priority. It can be used for redeclaring instances at the end of + sections, or declaring structure projections as instances. This is + equivalent to ``Hint Resolve ident : typeclass_instances``, except it + registers instances for :cmd:`Print Instances`. + +.. tacn:: typeclasses eauto + :name: typeclasses eauto + + This tactic uses a different resolution engine than :tacn:`eauto` and + :tacn:`auto`. The main differences are the following: + + + Contrary to :tacn:`eauto` and :tacn:`auto`, the resolution is done entirely in + the new proof engine (as of Coq 8.6), meaning that backtracking is + available among dependent subgoals, and shelving goals is supported. + ``typeclasses eauto`` is a multi-goal tactic. It analyses the dependencies + between subgoals to avoid backtracking on subgoals that are entirely + independent. + + + When called with no arguments, ``typeclasses eauto`` uses + the ``typeclass_instances`` database by default (instead of core). + Dependent subgoals are automatically shelved, and shelved goals can + remain after resolution ends (following the behavior of Coq 8.5). + + .. note:: + As of Coq 8.6, ``all:once (typeclasses eauto)`` faithfully + mimicks what happens during typeclass resolution when it is called + during refinement/type inference, except that *only* declared class + subgoals are considered at the start of resolution during type + inference, while ``all`` can select non-class subgoals as well. It might + move to ``all:typeclasses eauto`` in future versions when the + refinement engine will be able to backtrack. + + + When called with specific databases (e.g. with), ``typeclasses eauto`` + allows shelved goals to remain at any point during search and treat + typeclass goals like any other. + + + The transparency information of databases is used consistently for + all hints declared in them. It is always used when calling the + unifier. When considering local hypotheses, we use the transparent + state of the first hint database given. Using an empty database + (created with :cmd:`Create HintDb` for example) with unfoldable variables and + constants as the first argument of ``typeclasses eauto`` hence makes + resolution with the local hypotheses use full conversion during + unification. + + + .. cmdv:: typeclasses eauto @num + + .. warning:: + The semantics for the limit :n:`@num` + is different than for auto. By default, if no limit is given, the + search is unbounded. Contrary to :tacn:`auto`, introduction steps are + counted, which might result in larger limits being necessary when + searching with ``typeclasses eauto`` than with :tacn:`auto`. + + .. cmdv:: typeclasses eauto with {+ @ident} + + This variant runs resolution with the given hint databases. It treats + typeclass subgoals the same as other subgoals (no shelving of + non-typeclass goals in particular). + +.. tacn:: autoapply @term with @ident + :name: autoapply + + The tactic ``autoapply`` applies a term using the transparency information + of the hint database ident, and does *no* typeclass resolution. This can + be used in :cmd:`Hint Extern`’s for typeclass instances (in the hint + database ``typeclass_instances``) to allow backtracking on the typeclass + subgoals created by the lemma application, rather than doing typeclass + resolution locally at the hint application time. + +.. _TypeclassesTransparent: + +Typeclasses Transparent, Typclasses Opaque +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. cmd:: Typeclasses Transparent {+ @ident} + + This command makes the identifiers transparent during typeclass + resolution. + +.. cmd:: Typeclasses Opaque {+ @ident} + + Make the identifiers opaque for typeclass search. It is useful when some + constants prevent some unifications and make resolution fail. It is also + useful to declare constants which should never be unfolded during + proof-search, like fixpoints or anything which does not look like an + abbreviation. This can additionally speed up proof search as the typeclass + map can be indexed by such rigid constants (see + :ref:`thehintsdatabasesforautoandeauto`). + +By default, all constants and local variables are considered transparent. One +should take care not to make opaque any constant that is used to abbreviate a +type, like: + +.. coqdoc:: + Definition relation A := A -> A -> Prop. + +This is equivalent to ``Hint Transparent, Opaque ident : typeclass_instances``. + + +Settings +~~~~~~~~ + +.. flag:: Typeclasses Dependency Order + + This flag (on by default since 8.6) respects the dependency order + between subgoals, meaning that subgoals on which other subgoals depend + come first, while the non-dependent subgoals were put before + the dependent ones previously (Coq 8.5 and below). This can result in + quite different performance behaviors of proof search. + + +.. flag:: Typeclasses Filtered Unification + + This flag, available since Coq 8.6 and off by default, switches the + hint application procedure to a filter-then-unify strategy. To apply a + hint, we first check that the goal *matches* syntactically the + inferred or specified pattern of the hint, and only then try to + *unify* the goal with the conclusion of the hint. This can drastically + improve performance by calling unification less often, matching + syntactic patterns being very quick. This also provides more control + on the triggering of instances. For example, forcing a constant to + explicitly appear in the pattern will make it never apply on a goal + where there is a hole in that place. + + +.. flag:: Typeclasses Limit Intros + + This flag (on by default) controls the ability to apply hints while + avoiding (functional) eta-expansions in the generated proof term. It + does so by allowing hints that conclude in a product to apply to a + goal with a matching product directly, avoiding an introduction. + + .. warning:: + + This can be expensive as it requires rebuilding hint + clauses dynamically, and does not benefit from the invertibility + status of the product introduction rule, resulting in potentially more + expensive proof-search (i.e. more useless backtracking). + +.. flag:: Typeclass Resolution For Conversion + + This flag (on by default) controls the use of typeclass resolution + when a unification problem cannot be solved during elaboration/type + inference. With this flag on, when a unification fails, typeclass + resolution is tried before launching unification once again. + + +.. flag:: Typeclasses Strict Resolution + + Typeclass declarations introduced when this flag is set have a + stricter resolution behavior (the flag is off by default). When + looking for unifications of a goal with an instance of this class, we + “freeze” all the existentials appearing in the goals, meaning that + they are considered rigid during unification and cannot be + instantiated. + + +.. flag:: Typeclasses Unique Solutions + + When a typeclass resolution is launched we ensure that it has a single + solution or fail. This ensures that the resolution is canonical, but + can make proof search much more expensive. + + +.. flag:: Typeclasses Unique Instances + + Typeclass declarations introduced when this flag is set have a more + efficient resolution behavior (the flag is off by default). When a + solution to the typeclass goal of this class is found, we never + backtrack on it, assuming that it is canonical. + +.. flag:: Typeclasses Iterative Deepening + + When this flag is set, the proof search strategy is breadth-first search. + Otherwise, the search strategy is depth-first search. The default is off. + :cmd:`Typeclasses eauto` is another way to set this flag. + +.. opt:: Typeclasses Depth @num + :name: Typeclasses Depth + + Sets the maximum proof search depth. The default is unbounded. + :cmd:`Typeclasses eauto` is another way to set this option. + +.. flag:: Typeclasses Debug + + Controls whether typeclass resolution steps are shown during search. Setting this flag + also sets :opt:`Typeclasses Debug Verbosity` to 1. :cmd:`Typeclasses eauto` + is another way to set this flag. + +.. opt:: Typeclasses Debug Verbosity @num + :name: Typeclasses Debug Verbosity + + Determines how much information is shown for typeclass resolution steps during search. + 1 is the default level. 2 shows additional information such as tried tactics and shelving + of goals. Setting this option to 1 or 2 turns on :flag:`Typeclasses Debug`; setting this + option to 0 turns that option off. + +.. flag:: Refine Instance Mode + + .. deprecated:: 8.10 + + This flag allows to switch the behavior of instance declarations made through + the Instance command. + + + When it is off (the default), they fail with an error instead. + + + When it is on, instances that have unsolved holes in + their proof-term silently open the proof mode with the remaining + obligations to prove. + +Typeclasses eauto `:=` +~~~~~~~~~~~~~~~~~~~~~~ + +.. cmd:: Typeclasses eauto := {? debug} {? (dfs) | (bfs) } @num + :name: Typeclasses eauto + + This command allows more global customization of the typeclass + resolution tactic. The semantics of the options are: + + + ``debug`` This sets the debug mode. In debug mode, the trace of + successfully applied tactics is printed. The debug mode can also + be set with :flag:`Typeclasses Debug`. + + + ``(dfs)``, ``(bfs)`` This sets the search strategy to depth-first + search (the default) or breadth-first search. The search strategy + can also be set with :flag:`Typeclasses Iterative Deepening`. + + + :token:`num` This sets the depth limit of the search. The depth + limit can also be set with :opt:`Typeclasses Depth`. diff --git a/doc/sphinx/addendum/universe-polymorphism.rst b/doc/sphinx/addendum/universe-polymorphism.rst new file mode 100644 index 0000000000..6b10b7c0b3 --- /dev/null +++ b/doc/sphinx/addendum/universe-polymorphism.rst @@ -0,0 +1,502 @@ +.. _polymorphicuniverses: + +Polymorphic Universes +====================== + +:Author: Matthieu Sozeau + +General Presentation +--------------------- + +.. warning:: + + The status of Universe Polymorphism is experimental. + +This section describes the universe polymorphic extension of |Coq|. +Universe polymorphism makes it possible to write generic definitions +making use of universes and reuse them at different and sometimes +incompatible universe levels. + +A standard example of the difference between universe *polymorphic* +and *monomorphic* definitions is given by the identity function: + +.. coqtop:: in + + Definition identity {A : Type} (a : A) := a. + +By default, constant declarations are monomorphic, hence the identity +function declares a global universe (say ``Top.1``) for its domain. +Subsequently, if we try to self-apply the identity, we will get an +error: + +.. coqtop:: all + + Fail Definition selfid := identity (@identity). + +Indeed, the global level ``Top.1`` would have to be strictly smaller than +itself for this self-application to type check, as the type of +:g:`(@identity)` is :g:`forall (A : Type@{Top.1}), A -> A` whose type is itself +:g:`Type@{Top.1+1}`. + +A universe polymorphic identity function binds its domain universe +level at the definition level instead of making it global. + +.. coqtop:: in + + Polymorphic Definition pidentity {A : Type} (a : A) := a. + +.. coqtop:: all + + About pidentity. + +It is then possible to reuse the constant at different levels, like +so: + +.. coqtop:: in + + Definition selfpid := pidentity (@pidentity). + +Of course, the two instances of :g:`pidentity` in this definition are +different. This can be seen when the :flag:`Printing Universes` flag is on: + +.. coqtop:: none + + Set Printing Universes. + +.. coqtop:: all + + Print selfpid. + +Now :g:`pidentity` is used at two different levels: at the head of the +application it is instantiated at ``Top.3`` while in the argument position +it is instantiated at ``Top.4``. This definition is only valid as long as +``Top.4`` is strictly smaller than ``Top.3``, as shown by the constraints. Note +that this definition is monomorphic (not universe polymorphic), so the +two universes (in this case ``Top.3`` and ``Top.4``) are actually global +levels. + +When printing :g:`pidentity`, we can see the universes it binds in +the annotation :g:`@{Top.2}`. Additionally, when +:flag:`Printing Universes` is on we print the "universe context" of +:g:`pidentity` consisting of the bound universes and the +constraints they must verify (for :g:`pidentity` there are no constraints). + +Inductive types can also be declared universes polymorphic on +universes appearing in their parameters or fields. A typical example +is given by monoids: + +.. coqtop:: in + + Polymorphic Record Monoid := { mon_car :> Type; mon_unit : mon_car; + mon_op : mon_car -> mon_car -> mon_car }. + +.. coqtop:: in + + Print Monoid. + +The Monoid's carrier universe is polymorphic, hence it is possible to +instantiate it for example with :g:`Monoid` itself. First we build the +trivial unit monoid in :g:`Set`: + +.. coqtop:: in + + Definition unit_monoid : Monoid := + {| mon_car := unit; mon_unit := tt; mon_op x y := tt |}. + +From this we can build a definition for the monoid of :g:`Set`\-monoids +(where multiplication would be given by the product of monoids). + +.. coqtop:: in + + Polymorphic Definition monoid_monoid : Monoid. + refine (@Build_Monoid Monoid unit_monoid (fun x y => x)). + Defined. + +.. coqtop:: all + + Print monoid_monoid. + +As one can see from the constraints, this monoid is “large”, it lives +in a universe strictly higher than :g:`Set`. + +Polymorphic, Monomorphic +------------------------- + +.. cmd:: Polymorphic @definition + + As shown in the examples, polymorphic definitions and inductives can be + declared using the ``Polymorphic`` prefix. + +.. flag:: Universe Polymorphism + + Once enabled, this option will implicitly prepend ``Polymorphic`` to any + definition of the user. + +.. cmd:: Monomorphic @definition + + When the :flag:`Universe Polymorphism` option is set, to make a definition + producing global universe constraints, one can use the ``Monomorphic`` prefix. + +Many other commands support the ``Polymorphic`` flag, including: + +.. TODO add links on each of these? + +- ``Lemma``, ``Axiom``, and all the other “definition” keywords support + polymorphism. + +- ``Variables``, ``Context``, ``Universe`` and ``Constraint`` in a section support + polymorphism. This means that the universe variables (and associated + constraints) are discharged polymorphically over definitions that use + them. In other words, two definitions in the section sharing a common + variable will both get parameterized by the universes produced by the + variable declaration. This is in contrast to a “mononorphic” variable + which introduces global universes and constraints, making the two + definitions depend on the *same* global universes associated to the + variable. + +- :cmd:`Hint Resolve` and :cmd:`Hint Rewrite` will use the auto/rewrite hint + polymorphically, not at a single instance. + +Cumulative, NonCumulative +------------------------- + +Polymorphic inductive types, coinductive types, variants and records can be +declared cumulative using the :g:`Cumulative` prefix. + +.. cmd:: Cumulative @inductive + + Declares the inductive as cumulative + +Alternatively, there is a flag :flag:`Polymorphic Inductive +Cumulativity` which when set, makes all subsequent *polymorphic* +inductive definitions cumulative. When set, inductive types and the +like can be enforced to be non-cumulative using the :g:`NonCumulative` +prefix. + +.. cmd:: NonCumulative @inductive + + Declares the inductive as non-cumulative + +.. flag:: Polymorphic Inductive Cumulativity + + When this option is on, it sets all following polymorphic inductive + types as cumulative (it is off by default). + +Consider the examples below. + +.. coqtop:: in + + Polymorphic Cumulative Inductive list {A : Type} := + | nil : list + | cons : A -> list -> list. + +.. coqtop:: all + + Print list. + +When printing :g:`list`, the universe context indicates the subtyping +constraints by prefixing the level names with symbols. + +Because inductive subtypings are only produced by comparing inductives +to themselves with universes changed, they amount to variance +information: each universe is either invariant, covariant or +irrelevant (there are no contravariant subtypings in Coq), +respectively represented by the symbols `=`, `+` and `*`. + +Here we see that :g:`list` binds an irrelevant universe, so any two +instances of :g:`list` are convertible: :math:`E[Γ] ⊢ \mathsf{list}@\{i\}~A +=_{βδιζη} \mathsf{list}@\{j\}~B` whenever :math:`E[Γ] ⊢ A =_{βδιζη} B` and +this applies also to their corresponding constructors, when +they are comparable at the same type. + +See :ref:`Conversion-rules` for more details on convertibility and subtyping. +The following is an example of a record with non-trivial subtyping relation: + +.. coqtop:: all + + Polymorphic Cumulative Record packType := {pk : Type}. + +:g:`packType` binds a covariant universe, i.e. + +.. math:: + + E[Γ] ⊢ \mathsf{packType}@\{i\} =_{βδιζη} + \mathsf{packType}@\{j\}~\mbox{ whenever }~i ≤ j + +Cumulative inductive types, coinductive types, variants and records +only make sense when they are universe polymorphic. Therefore, an +error is issued whenever the user uses the :g:`Cumulative` or +:g:`NonCumulative` prefix in a monomorphic context. +Notice that this is not the case for the option :flag:`Polymorphic Inductive Cumulativity`. +That is, this option, when set, makes all subsequent *polymorphic* +inductive declarations cumulative (unless, of course the :g:`NonCumulative` prefix is used) +but has no effect on *monomorphic* inductive declarations. + +Consider the following examples. + +.. coqtop:: all reset + + Fail Monomorphic Cumulative Inductive Unit := unit. + +.. coqtop:: all reset + + Fail Monomorphic NonCumulative Inductive Unit := unit. + +.. coqtop:: all reset + + Set Polymorphic Inductive Cumulativity. + Inductive Unit := unit. + +An example of a proof using cumulativity +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. coqtop:: in + + Set Universe Polymorphism. + Set Polymorphic Inductive Cumulativity. + + Inductive eq@{i} {A : Type@{i}} (x : A) : A -> Type@{i} := eq_refl : eq x x. + + Definition funext_type@{a b e} (A : Type@{a}) (B : A -> Type@{b}) + := forall f g : (forall a, B a), + (forall x, eq@{e} (f x) (g x)) + -> eq@{e} f g. + + Section down. + Universes a b e e'. + Constraint e' < e. + Lemma funext_down {A B} + (H : @funext_type@{a b e} A B) : @funext_type@{a b e'} A B. + Proof. + exact H. + Defined. + End down. + +Cumulativity Weak Constraints +----------------------------- + +.. flag:: Cumulativity Weak Constraints + + When set, which is the default, causes "weak" constraints to be produced + when comparing universes in an irrelevant position. Processing weak + constraints is delayed until minimization time. A weak constraint + between `u` and `v` when neither is smaller than the other and + one is flexible causes them to be unified. Otherwise the constraint is + silently discarded. + + This heuristic is experimental and may change in future versions. + Disabling weak constraints is more predictable but may produce + arbitrary numbers of universes. + + +Global and local universes +--------------------------- + +Each universe is declared in a global or local environment before it +can be used. To ensure compatibility, every *global* universe is set +to be strictly greater than :g:`Set` when it is introduced, while every +*local* (i.e. polymorphically quantified) universe is introduced as +greater or equal to :g:`Set`. + + +Conversion and unification +--------------------------- + +The semantics of conversion and unification have to be modified a +little to account for the new universe instance arguments to +polymorphic references. The semantics respect the fact that +definitions are transparent, so indistinguishable from their bodies +during conversion. + +This is accomplished by changing one rule of unification, the first- +order approximation rule, which applies when two applicative terms +with the same head are compared. It tries to short-cut unfolding by +comparing the arguments directly. In case the constant is universe +polymorphic, we allow this rule to fire only when unifying the +universes results in instantiating a so-called flexible universe +variables (not given by the user). Similarly for conversion, if such +an equation of applicative terms fail due to a universe comparison not +being satisfied, the terms are unfolded. This change implies that +conversion and unification can have different unfolding behaviors on +the same development with universe polymorphism switched on or off. + + +Minimization +------------- + +Universe polymorphism with cumulativity tends to generate many useless +inclusion constraints in general. Typically at each application of a +polymorphic constant :g:`f`, if an argument has expected type :g:`Type@{i}` +and is given a term of type :g:`Type@{j}`, a :math:`j ≤ i` constraint will be +generated. It is however often the case that an equation :math:`j = i` would +be more appropriate, when :g:`f`\'s universes are fresh for example. +Consider the following example: + +.. coqtop:: none + + Polymorphic Definition pidentity {A : Type} (a : A) := a. + Set Printing Universes. + +.. coqtop:: in + + Definition id0 := @pidentity nat 0. + +.. coqtop:: all + + Print id0. + +This definition is elaborated by minimizing the universe of :g:`id0` to +level :g:`Set` while the more general definition would keep the fresh level +:g:`i` generated at the application of :g:`id` and a constraint that :g:`Set` :math:`≤ i`. +This minimization process is applied only to fresh universe variables. +It simply adds an equation between the variable and its lower bound if +it is an atomic universe (i.e. not an algebraic max() universe). + +.. flag:: Universe Minimization ToSet + + Turning this flag off (it is on by default) disallows minimization + to the sort :g:`Set` and only collapses floating universes between + themselves. + + +Explicit Universes +------------------- + +The syntax has been extended to allow users to explicitly bind names +to universes and explicitly instantiate polymorphic definitions. + +.. cmd:: Universe @ident + + In the monorphic case, this command declares a new global universe + named :g:`ident`, which can be referred to using its qualified name + as well. Global universe names live in a separate namespace. The + command supports the polymorphic flag only in sections, meaning the + universe quantification will be discharged on each section definition + independently. One cannot mix polymorphic and monomorphic + declarations in the same section. + + +.. cmd:: Constraint @ident @ord @ident + + This command declares a new constraint between named universes. The + order relation :n:`@ord` can be one of :math:`<`, :math:`≤` or :math:`=`. If consistent, the constraint + is then enforced in the global environment. Like ``Universe``, it can be + used with the ``Polymorphic`` prefix in sections only to declare + constraints discharged at section closing time. One cannot declare a + global constraint on polymorphic universes. + + .. exn:: Undeclared universe @ident. + :undocumented: + + .. exn:: Universe inconsistency. + :undocumented: + + +Polymorphic definitions +~~~~~~~~~~~~~~~~~~~~~~~ + +For polymorphic definitions, the declaration of (all) universe levels +introduced by a definition uses the following syntax: + +.. coqtop:: in + + Polymorphic Definition le@{i j} (A : Type@{i}) : Type@{j} := A. + +.. coqtop:: all + + Print le. + +During refinement we find that :g:`j` must be larger or equal than :g:`i`, as we +are using :g:`A : Type@{i} <= Type@{j}`, hence the generated constraint. At the +end of a definition or proof, we check that the only remaining +universes are the ones declared. In the term and in general in proof +mode, introduced universe names can be referred to in terms. Note that +local universe names shadow global universe names. During a proof, one +can use :cmd:`Show Universes` to display the current context of universes. + +Definitions can also be instantiated explicitly, giving their full +instance: + +.. coqtop:: all + + Check (pidentity@{Set}). + Monomorphic Universes k l. + Check (le@{k l}). + +User-named universes and the anonymous universe implicitly attached to +an explicit :g:`Type` are considered rigid for unification and are never +minimized. Flexible anonymous universes can be produced with an +underscore or by omitting the annotation to a polymorphic definition. + +.. coqtop:: all + + Check (fun x => x) : Type -> Type. + Check (fun x => x) : Type -> Type@{_}. + + Check le@{k _}. + Check le. + +.. flag:: Strict Universe Declaration + + Turning this option off allows one to freely use + identifiers for universes without declaring them first, with the + semantics that the first use declares it. In this mode, the universe + names are not associated with the definition or proof once it has been + defined. This is meant mainly for debugging purposes. + +.. flag:: Private Polymorphic Universes + + This option, on by default, removes universes which appear only in + the body of an opaque polymorphic definition from the definition's + universe arguments. As such, no value needs to be provided for + these universes when instanciating the definition. Universe + constraints are automatically adjusted. + + Consider the following definition: + + .. coqtop:: all + + Lemma foo@{i} : Type@{i}. + Proof. exact Type. Qed. + Print foo. + + The universe :g:`Top.xxx` for the :g:`Type` in the body cannot be accessed, we + only care that one exists for any instantiation of the universes + appearing in the type of :g:`foo`. This is guaranteed when the + transitive constraint ``Set <= Top.xxx < i`` is verified. Then when + using the constant we don't need to put a value for the inner + universe: + + .. coqtop:: all + + Check foo@{_}. + + and when not looking at the body we don't mention the private + universe: + + .. coqtop:: all + + About foo. + + To recover the same behaviour with regard to universes as + :g:`Defined`, the option :flag:`Private Polymorphic Universes` may + be unset: + + .. coqtop:: all + + Unset Private Polymorphic Universes. + + Lemma bar : Type. Proof. exact Type. Qed. + About bar. + Fail Check bar@{_}. + Check bar@{_ _}. + + Note that named universes are always public. + + .. coqtop:: all + + Set Private Polymorphic Universes. + Unset Strict Universe Declaration. + + Lemma baz : Type@{outer}. Proof. exact Type@{inner}. Qed. + About baz. diff --git a/doc/sphinx/biblio.bib b/doc/sphinx/biblio.bib new file mode 100644 index 0000000000..0467852b19 --- /dev/null +++ b/doc/sphinx/biblio.bib @@ -0,0 +1,553 @@ +@String{jfp = "Journal of Functional Programming"} +@String{lncs = "Lecture Notes in Computer Science"} +@String{lnai = "Lecture Notes in Artificial Intelligence"} +@String{SV = "{Springer-Verlag}"} + +@InCollection{Asp00, + Title = {Proof General: A Generic Tool for Proof Development}, + Author = {Aspinall, David}, + Booktitle = {Tools and Algorithms for the Construction and + Analysis of Systems, {TACAS} 2000}, + Publisher = {Springer Berlin Heidelberg}, + Year = {2000}, + Editor = {Graf, Susanne and Schwartzbach, Michael}, + Pages = {38--43}, + Series = {Lecture Notes in Computer Science}, + Volume = {1785}, + Doi = {10.1007/3-540-46419-0_3}, + ISBN = {978-3-540-67282-1}, +} + +@Book{Bar81, + author = {H.P. Barendregt}, + publisher = {North-Holland}, + title = {The Lambda Calculus its Syntax and Semantics}, + year = {1981} +} + +@InProceedings{Bou97, + title = {Using reflection to build efficient and certified decision procedure +s}, + author = {S. Boutin}, + booktitle = {TACS'97}, + editor = {Martin Abadi and Takahashi Ito}, + publisher = SV, + series = lncs, + volume = 1281, + year = {1997} +} + +@Article{Bru72, + author = {N.J. de Bruijn}, + journal = {Indag. Math.}, + title = {{Lambda-Calculus Notation with Nameless Dummies, a Tool for Automatic Formula Manipulation, with Application to the Church-Rosser Theorem}}, + volume = {34}, + year = {1972} +} + +@inproceedings{CH85, + title={Constructions: a higher order proof system for mechanizing mathematics}, + author={Coquand, Thierry and Huet, Gérard}, + booktitle={European Conference on Computer Algebra}, + pages={151--184}, + year={1985}, + issn = {1611-3349}, + doi = {10.1007/3-540-15983-5_13}, + url = {http://dx.doi.org/10.1007/3-540-15983-5_13}, + isbn = 9783540396840, + publisher = {Springer Berlin Heidelberg} +} + +@techreport{CH88 + TITLE = {{The calculus of constructions}}, + AUTHOR = {Coquand, T. and Huet, G{\'e}rard}, + URL = {https://hal.inria.fr/inria-00076024}, + NUMBER = {RR-0530}, + INSTITUTION = {{INRIA}}, + YEAR = {1986}, + MONTH = May, + PDF = {https://hal.inria.fr/inria-00076024/file/RR-0530.pdf}, + HAL_ID = {inria-00076024}, + HAL_VERSION = {v1}, +} + +@techreport{CH87, + TITLE = {{Concepts mathematiques et informatiques formalises dans le calcul des constructions}}, + AUTHOR = {Coquand, T. and Huet, G{\'e}rard}, + URL = {https://hal.inria.fr/inria-00076039}, + NUMBER = {RR-0515}, + INSTITUTION = {{INRIA}}, + YEAR = {1986}, + MONTH = Apr, + PDF = {https://hal.inria.fr/inria-00076039/file/RR-0515.pdf}, + HAL_ID = {inria-00076039}, + HAL_VERSION = {v1}, +} + +@techreport{C90, + TITLE = {{Metamathematical investigations of a calculus of constructions}}, + AUTHOR = {Coquand, T.}, + URL = {https://hal.inria.fr/inria-00075471}, + NUMBER = {RR-1088}, + INSTITUTION = {{INRIA}}, + YEAR = {1989}, + MONTH = Sep, + PDF = {https://hal.inria.fr/inria-00075471/file/RR-1088.pdf}, + HAL_ID = {inria-00075471}, + HAL_VERSION = {v1}, +} + +@PhDThesis{Coq85, + author = {Th. Coquand}, + month = jan, + school = {Universit\'e Paris~7}, + title = {Une Th\'eorie des Constructions}, + year = {1985} +} + +@InProceedings{Coq86, + author = {Th. Coquand}, + address = {Cambridge, MA}, + booktitle = {Symposium on Logic in Computer Science}, + publisher = {IEEE Computer Society Press}, + title = {{An Analysis of Girard's Paradox}}, + year = {1986} +} + +@InProceedings{Coq92, + author = {Th. Coquand}, + title = {{Pattern Matching with Dependent Types}}, + year = {1992}, + booktitle = {Proceedings of the 1992 Workshop on Types for Proofs and Programs} +} + +@InProceedings{DBLP:conf/types/CornesT95, + author = {Cristina Cornes and + Delphine Terrasse}, + title = {Automating Inversion of Inductive Predicates in Coq}, + booktitle = {TYPES}, + year = {1995}, + pages = {85-104}, + crossref = {DBLP:conf/types/1995}, + bibsource = {DBLP, http://dblp.uni-trier.de} +} + +@inproceedings{CP90, + title={Inductively defined types}, + author={Coquand, Thierry and Paulin, Christine}, + booktitle={COLOG-88}, + pages={50--66}, + year={1990}, + issn = {1611-3349}, + doi = {10.1007/3-540-52335-9_47}, + url = {http://dx.doi.org/10.1007/3-540-52335-9_47}, + isbn = 9783540469636, + publisher = {Springer Berlin Heidelberg} +} + +@Book{Cur58, + author = {Haskell B. Curry and Robert Feys and William Craig}, + title = {Combinatory Logic}, + volume = 1, + publisher = "North-Holland", + year = 1958, + note = {{\S{9E}}}, +} + +@Article{CSlessadhoc, + author = {Gonthier, Georges and Ziliani, Beta and Nanevski, Aleksandar and Dreyer, Derek}, + title = {How to Make Ad Hoc Proof Automation Less Ad Hoc}, + journal = {SIGPLAN Not.}, + issue_date = {September 2011}, + volume = {46}, + number = {9}, + month = sep, + year = {2011}, + issn = {0362-1340}, + pages = {163--175}, + numpages = {13}, + url = {http://doi.acm.org/10.1145/2034574.2034798}, + doi = {10.1145/2034574.2034798}, + acmid = {2034798}, + publisher = {ACM}, + address = {New York, NY, USA}, + keywords = {canonical structures, coq, custom proof automation, hoare type theory, interactive theorem proving, tactics, type classes}, +} + +@InProceedings{CSwcu, + hal_id = {hal-00816703}, + url = {http://hal.inria.fr/hal-00816703}, + title = {{Canonical Structures for the working Coq user}}, + author = {Mahboubi, Assia and Tassi, Enrico}, + booktitle = {{ITP 2013, 4th Conference on Interactive Theorem Proving}}, + publisher = {Springer}, + pages = {19-34}, + address = {Rennes, France}, + volume = {7998}, + editor = {Sandrine Blazy and Christine Paulin and David Pichardie }, + series = {LNCS }, + doi = {10.1007/978-3-642-39634-2_5}, + year = {2013}, +} + +@InProceedings{Del00, + author = {Delahaye, D.}, + title = {A {T}actic {L}anguage for the {S}ystem {{\sf Coq}}}, + booktitle = {Proceedings of Logic for Programming and Automated Reasoning + (LPAR), Reunion Island}, + publisher = SV, + series = LNCS, + volume = {1955}, + pages = {85--95}, + month = {November}, + year = {2000}, + url = {http://www.lirmm.fr/%7Edelahaye/papers/ltac%20(LPAR%2700).pdf} +} + +@Article{Dyc92, + author = {Roy Dyckhoff}, + journal = {The Journal of Symbolic Logic}, + month = sep, + number = {3}, + title = {Contraction-free sequent calculi for intuitionistic logic}, + volume = {57}, + year = {1992} +} + +@Book{Fourier, + author = {Jean-Baptiste-Joseph Fourier}, + publisher = {Gauthier-Villars}, + title = {Fourier's method to solve linear + inequations/equations systems.}, + year = {1890} +} + +@InProceedings{Gim94, + author = {E. Gim\'enez}, + booktitle = {Types'94 : Types for Proofs and Programs}, + note = {Extended version in LIP research report 95-07, ENS Lyon}, + publisher = SV, + series = LNCS, + title = {Codifying guarded definitions with recursive schemes}, + volume = {996}, + year = {1994} +} + +@TechReport{Gim98, + author = {E. Gim\'enez}, + title = {A Tutorial on Recursive Types in Coq}, + institution = {INRIA}, + year = 1998, + month = mar +} + +@Unpublished{GimCas05, + author = {E. Gim\'enez and P. Cast\'eran}, + title = {A Tutorial on [Co-]Inductive Types in Coq}, + institution = {INRIA}, + year = 2005, + month = jan, + note = {available at \url{http://coq.inria.fr/doc}} +} + +@InProceedings{Gimenez95b, + author = {E. Gim\'enez}, + booktitle = {Workshop on Types for Proofs and Programs}, + series = LNCS, + number = {1158}, + pages = {135-152}, + title = {An application of co-Inductive types in Coq: + verification of the Alternating Bit Protocol}, + editorS = {S. Berardi and M. Coppo}, + publisher = SV, + year = {1995} +} + +@Book{Gir89, + author = {J.-Y. Girard and Y. Lafont and P. Taylor}, + publisher = {Cambridge University Press}, + series = {Cambridge Tracts in Theoretical Computer Science 7}, + title = {Proofs and Types}, + year = {1989} +} + +@InCollection{How80, + author = {W.A. Howard}, + booktitle = {to H.B. Curry : Essays on Combinatory Logic, Lambda Calculus and Formalism.}, + editor = {J.P. Seldin and J.R. Hindley}, + note = {Unpublished 1969 Manuscript}, + publisher = {Academic Press}, + title = {The Formulae-as-Types Notion of Constructions}, + year = {1980} +} + +@inproceedings{H88, + title={Induction principles formalized in the Calculus of Constructions}, + author={Huet, G{\'e}rard}, + booktitle={Programming of Future Generation Computers. Elsevier Science}, + year={1988}, + issn = {1611-3349}, + doi = {10.1007/3-540-17660-8_62}, + url = {http://dx.doi.org/10.1007/3-540-17660-8_62}, + isbn = 9783540477464, + publisher = {Springer Berlin Heidelberg} +} + +@InProceedings{H89, + author = {G. Huet}, + booktitle = {A perspective in Theoretical Computer Science. Commemorative Volume for Gift Siromoney}, + editor = {R. Narasimhan}, + publisher = {World Scientific Publishing}, + title = {{The Constructive Engine}}, + year = {1989} +} + +@Article{LeeWerner11, + author = {Gyesik Lee and + Benjamin Werner}, + title = {Proof-irrelevant model of {CC} with predicative induction + and judgmental equality}, + journal = {Logical Methods in Computer Science}, + volume = {7}, + number = {4}, + year = {2011}, + ee = {http://dx.doi.org/10.2168/LMCS-7(4:5)2011}, + bibsource = {DBLP, http://dblp.uni-trier.de} +} + +@TechReport{Leroy90, + author = {X. Leroy}, + title = {The {ZINC} experiment: an economical implementation of the {ML} language}, + institution = {INRIA}, + number = {117}, + year = {1990} +} + +@InProceedings{Let02, + author = {P. Letouzey}, + title = {A New Extraction for Coq}, + booktitle = {TYPES}, + year = 2002, + crossref = {DBLP:conf/types/2002}, + url = {http://www.irif.fr/~letouzey/download/extraction2002.pdf} +} + +@InProceedings{Luttik97specificationof, + author = {Sebastiaan P. Luttik and Eelco Visser}, + booktitle = {2nd International Workshop on the Theory and Practice of Algebraic Specifications (ASF+SDF'97), Electronic Workshops in Computing}, + publisher = SV, + title = {Specification of Rewriting Strategies}, + year = {1997} +} + +@InProceedings{DBLP:conf/types/McBride00, + author = {Conor McBride}, + title = {Elimination with a Motive}, + booktitle = {TYPES}, + year = {2000}, + pages = {197-216}, + ee = {http://link.springer.de/link/service/series/0558/bibs/2277/22770197.htm}, + crossref = {DBLP:conf/types/2000}, + bibsource = {DBLP, http://dblp.uni-trier.de} +} + +@InProceedings{Moh93, + author = {C. Paulin-Mohring}, + booktitle = {Proceedings of the conference Typed Lambda Calculi and Applications}, + editor = {M. Bezem and J.-F. Groote}, + note = {Also LIP research report 92-49, ENS Lyon}, + number = {664}, + publisher = SV, + series = {LNCS}, + title = {{Inductive Definitions in the System Coq - Rules and Properties}}, + year = {1993} +} + +@MastersThesis{Mun94, + author = {C. Muñoz}, + month = sep, + school = {DEA d'Informatique Fondamentale, Universit\'e Paris 7}, + title = {D\'emonstration automatique dans la logique propositionnelle intuitionniste}, + year = {1994} +} + +@Article{Myers, + author = {Eugene Myers}, + title = {An {O(ND)} difference algorithm and its variations}, + journal = {Algorithmica}, + volume = {1}, + number = {2}, + year = {1986}, + bibsource = {https://link.springer.com/article/10.1007\%2FBF01840446}, + url = {http://www.xmailserver.org/diff2.pdf} +} + +@inproceedings{P86, + title={Algorithm development in the calculus of constructions}, + author={Mohring, Christine}, + booktitle={LICS}, + pages={84--91}, + year={1986} +} + +@inproceedings{P89, + title={Extracting $\Omega$'s programs from proofs in the calculus of constructions}, + author={Paulin-Mohring, Christine}, + booktitle={Proceedings of the 16th ACM SIGPLAN-SIGACT symposium on Principles of programming languages}, + pages={89--104}, + year={1989}, + doi = {10.1145/75277.75285}, + url = {http://dx.doi.org/10.1145/75277.75285}, + isbn = 0897912942, + organization = {ACM Press} +} + +@inproceedings{P93, + title={Inductive definitions in the system coq rules and properties}, + author={Paulin-Mohring, Christine}, + booktitle={International Conference on Typed Lambda Calculi and Applications}, + pages={328--345}, + year={1993}, + doi = {10.1007/bfb0037116}, + url = {http://dx.doi.org/10.1007/bfb0037116}, + isbn = 3540565175, + organization = {Springer-Verlag} +} + +@inproceedings{PP90, + title={Inductively defined types in the Calculus of Constructions}, + author={Pfenning, Frank and Paulin-Mohring, Christine}, + booktitle={International Conference on Mathematical Foundations of Programming Semantics}, + pages={209--228}, + year={1989}, + doi = {10.1007/bfb0040259}, + url = {http://dx.doi.org/10.1007/bfb0040259}, + isbn = 0387973753, + organization = {Springer-Verlag} +} + +@InProceedings{Parent95b, + author = {C. Parent}, + booktitle = {{Mathematics of Program Construction'95}}, + publisher = SV, + series = {LNCS}, + title = {{Synthesizing proofs from programs in +the Calculus of Inductive Constructions}}, + volume = {947}, + year = {1995} +} + +@InProceedings{Pit16, + Title = {Company-Coq: Taking Proof General one step closer to a real IDE}, + Author = {Pit-Claudel, Clément and Courtieu, Pierre}, + Booktitle = {CoqPL'16: The Second International Workshop on Coq for PL}, + Year = {2016}, + Month = jan, + Doi = {10.5281/zenodo.44331}, +} + +@Book{RC95, + author = {di~Cosmo, R.}, + title = {Isomorphisms of Types: from $\lambda$-calculus to information + retrieval and language design}, + series = {Progress in Theoretical Computer Science}, + publisher = {Birkhauser}, + year = {1995}, + note = {ISBN-0-8176-3763-X} +} + +@Article{Rushby98, + title = {Subtypes for Specifications: Predicate Subtyping in + {PVS}}, + author = {John Rushby and Sam Owre and N. Shankar}, + journal = {IEEE Transactions on Software Engineering}, + pages = {709--720}, + volume = 24, + number = 9, + month = sep, + year = 1998 +} + +@InProceedings{sozeau06, + author = {Matthieu Sozeau}, + title = {Subset Coercions in {C}oq}, + year = {2007}, + booktitle = {TYPES'06}, + pages = {237-252}, + volume = {4502}, + publisher = "Springer", + series = {LNCS} +} + +@InProceedings{sozeau08, + Author = {Matthieu Sozeau and Nicolas Oury}, + booktitle = {TPHOLs'08}, + Pdf = {http://www.lri.fr/~sozeau/research/publications/drafts/classes.pdf}, + Title = {{F}irst-{C}lass {T}ype {C}lasses}, + Year = {2008}, +} + +@InProceedings{sugar, + author = {Alessandro Giovini and Teo Mora and Gianfranco Niesi and Lorenzo Robbiano and Carlo Traverso}, + title = {"One sugar cube, please" or Selection strategies in the Buchberger algorithm}, + booktitle = { Proceedings of the ISSAC'91, ACM Press}, + year = {1991}, + pages = {5--4}, + publisher = {} +} + +@Article{TheOmegaPaper, + author = "W. Pugh", + title = "The Omega test: a fast and practical integer programming algorithm for dependence analysis", + journal = "Communication of the ACM", + pages = "102--114", + year = "1992", +} + +@PhDThesis{Wer94, + author = {B. Werner}, + school = {Universit\'e Paris 7}, + title = {Une th\'eorie des constructions inductives}, + type = {Th\`ese de Doctorat}, + year = {1994} +} + +@InProceedings{CompiledStrongReduction, + author = {Benjamin Gr{\'{e}}goire and + Xavier Leroy}, + editor = {Mitchell Wand and + Simon L. Peyton Jones}, + title = {A compiled implementation of strong reduction}, + booktitle = {Proceedings of the Seventh {ACM} {SIGPLAN} International Conference + on Functional Programming {(ICFP} '02), Pittsburgh, Pennsylvania, + USA, October 4-6, 2002.}, + pages = {235--246}, + publisher = {{ACM}}, + year = {2002}, + url = {http://doi.acm.org/10.1145/581478.581501}, + doi = {10.1145/581478.581501}, + timestamp = {Tue, 11 Jun 2013 13:49:16 +0200}, + biburl = {http://dblp.uni-trier.de/rec/bib/conf/icfp/GregoireL02}, + bibsource = {dblp computer science bibliography, http://dblp.org} +} + +@InProceedings{FullReduction, + author = {Mathieu Boespflug and + Maxime D{\'{e}}n{\`{e}}s and + Benjamin Gr{\'{e}}goire}, + editor = {Jean{-}Pierre Jouannaud and + Zhong Shao}, + title = {Full Reduction at Full Throttle}, + booktitle = {Certified Programs and Proofs - First International Conference, {CPP} + 2011, Kenting, Taiwan, December 7-9, 2011. Proceedings}, + series = {Lecture Notes in Computer Science}, + volume = {7086}, + pages = {362--377}, + publisher = {Springer}, + year = {2011}, + url = {http://dx.doi.org/10.1007/978-3-642-25379-9_26}, + doi = {10.1007/978-3-642-25379-9_26}, + timestamp = {Thu, 17 Nov 2011 13:33:48 +0100}, + biburl = {http://dblp.uni-trier.de/rec/bib/conf/cpp/BoespflugDG11}, + bibsource = {dblp computer science bibliography, http://dblp.org} +} diff --git a/doc/sphinx/changes.rst b/doc/sphinx/changes.rst new file mode 100644 index 0000000000..57b9e45342 --- /dev/null +++ b/doc/sphinx/changes.rst @@ -0,0 +1,4892 @@ +-------------- +Recent changes +-------------- + +Version 8.9 +----------- + +Summary of changes +~~~~~~~~~~~~~~~~~~ + +|Coq| version 8.9 contains the result of refinements and stabilization +of features and deprecations or removals of deprecated features, +cleanups of the internals of the system and API along with a few new +features. This release includes many user-visible changes, including +deprecations that are documented in ``CHANGES.md`` and new features that +are documented in the reference manual. Here are the most important +changes: + +- Kernel: mutually recursive records are now supported, by Pierre-Marie + Pédrot. + +- Notations: + + - Support for autonomous grammars of terms called “custom entries”, by + Hugo Herbelin (see Section :ref:`custom-entries` of the reference + manual). + + - Deprecated notations of the standard library will be removed in the + next version of |Coq|, see the ``CHANGES.md`` file for a script to + ease porting, by Jason Gross and Jean-Christophe Léchenet. + + - Added the :cmd:`Numeral Notation` command for registering decimal + numeral notations for custom types, by Daniel de Rauglaudre, Pierre + Letouzey and Jason Gross. + +- Tactics: Introduction tactics :tacn:`intro`/:tacn:`intros` on a goal that is an + existential variable now force a refinement of the goal into a + dependent product rather than failing, by Hugo Herbelin. + +- Decision procedures: deprecation of tactic ``romega`` in favor of + :tacn:`lia` and removal of ``fourier``, replaced by :tacn:`lra` which + subsumes it, by Frédéric Besson, Maxime Dénès, Vincent Laporte and + Laurent Théry. + +- Proof language: focusing bracket ``{`` now supports named + :ref:`goals <curly-braces>`, e.g. ``[x]:{`` will focus + on a goal (existential variable) named ``x``, by Théo Zimmermann. + +- SSReflect: the implementation of delayed clear was simplified by + Enrico Tassi: the variables are always renamed using inaccessible + names when the clear switch is processed and finally cleared at the + end of the intro pattern. In addition to that, the use-and-discard flag + ``{}`` typical of rewrite rules can now be also applied to views, + e.g. ``=> {}/v`` applies ``v`` and then clears ``v``. See Section + :ref:`introduction_ssr`. + +- Vernacular: + + - Experimental support for :ref:`attributes <gallina-attributes>` on + commands, by Vincent Laporte, as in ``#[local] Lemma foo : bar.`` + Tactics and tactic notations now support the ``deprecated`` + attribute. + + - Removed deprecated commands ``Arguments Scope`` and ``Implicit + Arguments`` in favor of :cmd:`Arguments`, with the help of Jasper + Hugunin. + + - New flag :flag:`Uniform Inductive Parameters` by Jasper Hugunin to + avoid repeating uniform parameters in constructor declarations. + + - New commands :cmd:`Hint Variables` and :cmd:`Hint Constants`, by + Matthieu Sozeau, for controlling the opacity status of variables and + constants in hint databases. It is recommended to always use these + commands after creating a hint databse with :cmd:`Create HintDb`. + + - Multiple sections with the same name are now allowed, by Jasper + Hugunin. + +- Library: additions and changes in the ``VectorDef``, ``Ascii``, and + ``String`` libraries. Syntax notations are now available only when using + ``Import`` of libraries and not merely ``Require``, by various + contributors (source of incompatibility, see ``CHANGES.md`` for details). + +- Toplevels: ``coqtop`` and ``coqide`` can now display diffs between proof + steps in color, using the :opt:`Diffs` option, by Jim Fehrle. + +- Documentation: we integrated a large number of fixes to the new Sphinx + documentation by various contributors, coordinated by Clément + Pit-Claudel and Théo Zimmermann. + +- Tools: removed the ``gallina`` utility and the homebrewed ``Emacs`` mode. + +- Packaging: as in |Coq| 8.8.2, the Windows installer now includes many + more external packages that can be individually selected for + installation, by Michael Soegtrop. + +Version 8.9 also comes with a bunch of smaller-scale changes and +improvements regarding the different components of the system. Most +important ones are documented in the ``CHANGES.md`` file. + +On the implementation side, the ``dev/doc/changes.md`` file documents +the numerous changes to the implementation and improvements of +interfaces. The file provides guidelines on porting a plugin to the new +version and a plugin development tutorial kept in sync with Coq was +introduced by Yves Bertot http://github.com/ybertot/plugin_tutorials. +The new ``dev/doc/critical-bugs`` file documents the known critical bugs +of |Coq| and affected releases. + +The efficiency of the whole system has seen improvements thanks to +contributions from Gaëtan Gilbert, Pierre-Marie Pédrot, and Maxime Dénès. + +Maxime Dénès, Emilio Jesús Gallego Arias, Gaëtan Gilbert, Michael +Soegtrop, Théo Zimmermann worked on maintaining and improving the +continuous integration system. + +The OPAM repository for |Coq| packages has been maintained by Guillaume +Melquiond, Matthieu Sozeau, Enrico Tassi with contributions from many +users. A list of packages is available at https://coq.inria.fr/opam/www/. + +The 54 contributors for this version are Léo Andrès, Rin Arakaki, +Benjamin Barenblat, Langston Barrett, Siddharth Bhat, Martin Bodin, +Simon Boulier, Timothy Bourke, Joachim Breitner, Tej Chajed, Arthur +Charguéraud, Pierre Courtieu, Maxime Dénès, Andres Erbsen, Jim Fehrle, +Julien Forest, Emilio Jesus Gallego Arias, Gaëtan Gilbert, Matěj +Grabovský, Jason Gross, Samuel Gruetter, Armaël Guéneau, Hugo Herbelin, +Jasper Hugunin, Ralf Jung, Sam Pablo Kuper, Ambroise Lafont, Leonidas +Lampropoulos, Vincent Laporte, Peter LeFanu Lumsdaine, Pierre Letouzey, +Jean-Christophe Léchenet, Nick Lewycky, Yishuai Li, Sven M. Hallberg, +Assia Mahboubi, Cyprien Mangin, Guillaume Melquiond, Perry E. Metzger, +Clément Pit-Claudel, Pierre-Marie Pédrot, Daniel R. Grayson, Kazuhiko +Sakaguchi, Michael Soegtrop, Matthieu Sozeau, Paul Steckler, Enrico +Tassi, Laurent Théry, Anton Trunov, whitequark, Théo Winterhalter, +Zeimer, Beta Ziliani, Théo Zimmermann. + +Many power users helped to improve the design of the new features via +the issue and pull request system, the |Coq| development mailing list or +the coq-club@inria.fr mailing list. It would be impossible to mention +exhaustively the names of everybody who to some extent influenced the +development. + +Version 8.9 is the fourth release of |Coq| developed on a time-based +development cycle. Its development spanned 7 months from the release of +|Coq| 8.8. The development moved to a decentralized merging process +during this cycle. Guillaume Melquiond was in charge of the release +process and is the maintainer of this release. This release is the +result of ~2,000 commits and ~500 PRs merged, closing 75+ issues. + +The |Coq| development team welcomed Vincent Laporte, a new |Coq| +engineer working with Maxime Dénès in the |Coq| consortium. + +| Paris, November 2018, +| Matthieu Sozeau for the |Coq| development team +| + +Details of changes +~~~~~~~~~~~~~~~~~~ + +Kernel + +- Mutually defined records are now supported. + +Notations + +- New support for autonomous grammars of terms, called "custom + entries" (see chapter "Syntax extensions" of the reference manual). + +- Deprecated compatibility notations will actually be removed in the + next version of Coq. Uses of these notations are generally easy to + fix thanks to the hint contained in the deprecation warnings. For + projects that require more than a handful of such fixes, there is [a + script](https://gist.github.com/JasonGross/9770653967de3679d131c59d42de6d17#file-replace-notations-py) + that will do it automatically, using the output of coqc. The script + contains documentation on its usage in a comment at the top. + +- When several notations are available for the same expression, + priority is given to latest notations defined in the scopes being + opened, in order, rather than to the latest notations defined + independently of whether they are in an opened scope or not. + +Tactics + +- Added toplevel goal selector `!` which expects a single focused goal. + Use with `Set Default Goal Selector` to force focusing before tactics + are called. + +- The undocumented "nameless" forms `fix N`, `cofix` that were + deprecated in 8.8 have been removed from Ltac's syntax; please use + `fix ident N/cofix ident` to explicitly name the (co)fixpoint + hypothesis to be introduced. + +- Introduction tactics `intro`/`intros` on a goal that is an + existential variable now force a refinement of the goal into a + dependent product rather than failing. + +- Support for `fix`/`cofix` added in Ltac `match` and `lazymatch`. + +- Ltac backtraces now include trace information about tactics + called by OCaml-defined tactics. + +- Option `Ltac Debug` now applies also to terms built using Ltac functions. + +- Deprecated the `Implicit Tactic` family of commands. + +- The default program obligation tactic uses a bounded proof search + instead of an unbounded and potentially non-terminating one now + (source of incompatibility). + +- The `simple apply` tactic now respects the `Opaque` flag when called from + Ltac (`auto` still does not respect it). + +- Tactic `constr_eq` now adds universe constraints needed for the + identity to the context (it used to ignore them). New tactic + `constr_eq_strict` checks that the required constraints already hold + without adding new ones. Preexisting tactic `constr_eq_nounivs` can + still be used if you really want to ignore universe constraints. + +- Tactics and tactic notations now understand the `deprecated` attribute. +- The `fourier` tactic has been removed. Please now use `lra` instead. You + may need to add `Require Import Lra` to your developments. For compatibility, + we now define `fourier` as a deprecated alias of `lra`. + +- The `romega` tactics have been deprecated; please use `lia` instead. + +Focusing + +- Focusing bracket `{` now supports named goal selectors, + e.g. `[x]: {` will focus on a goal (existential variable) named `x`. + As usual, unfocus with `}` once the sub-goal is fully solved. + +Specification language + +- A fix to unification (which was sensitive to the ascii name of + variables) may occasionally change type inference in incompatible + ways, especially regarding the inference of the return clause of `match`. + +Standard Library + +- Added `Ascii.eqb` and `String.eqb` and the `=?` notation for them, + and proved some lemmas about them. Note that this might cause + incompatibilities if you have, e.g., `string_scope` and `Z_scope` both + open with `string_scope` on top, and expect `=?` to refer to `Z.eqb`. + Solution: wrap `_ =? _` in `(_ =? _)%Z` (or whichever scope you + want). + +- Added `Ndigits.N2Bv_sized`, and proved some lemmas about it. + Deprecated `Ndigits.N2Bv_gen`. + +- The scopes `int_scope` and `uint_scope` have been renamed to + `dec_int_scope` and `dec_uint_scope`, to clash less with ssreflect + and other packages. They are still delimited by `%int` and `%uint`. + +- Syntax notations for `string`, `ascii`, `Z`, `positive`, `N`, `R`, + and `int31` are no longer available merely by `Require`ing the files + that define the inductives. You must `Import` `Coq.Strings.String.StringSyntax` + (after `Require` `Coq.Strings.String`), `Coq.Strings.Ascii.AsciiSyntax` (after + `Require` `Coq.Strings.Ascii`), `Coq.ZArith.BinIntDef`, `Coq.PArith.BinPosDef`, + `Coq.NArith.BinNatDef`, `Coq.Reals.Rdefinitions`, and + `Coq.Numbers.Cyclic.Int31.Int31`, respectively, to be able to use + these notations. Note that passing `-compat 8.8` or issuing + `Require Import Coq.Compat.Coq88` will make these notations + available. Users wishing to port their developments automatically + may download `fix.py` from + <https://gist.github.com/JasonGross/5d4558edf8f5c2c548a3d96c17820169> + and run a command like `while true; do make -Okj 2>&1 | + /path/to/fix.py; done` and get a cup of coffee. (This command must + be manually interrupted once the build finishes all the way though. + Note also that this method is not fail-proof; you may have to adjust + some scopes if you were relying on string notations not being + available even when `string_scope` was open.) + +- Numeral syntax for `nat` is no longer available without loading the + entire prelude (`Require Import Coq.Init.Prelude`). This only + impacts users running Coq without the init library (`-nois` or + `-noinit`) and also issuing `Require Import Coq.Init.Datatypes`. + +Tools + +- Coq_makefile lets one override or extend the following variables from + the command line: `COQFLAGS`, `COQCHKFLAGS`, `COQDOCFLAGS`. + `COQFLAGS` is now entirely separate from `COQLIBS`, so in custom Makefiles + `$(COQFLAGS)` should be replaced by `$(COQFLAGS) $(COQLIBS)`. + +- Removed the `gallina` utility (extracts specification from Coq vernacular files). + If you would like to maintain this tool externally, please contact us. + +- Removed the Emacs modes distributed with Coq. You are advised to + use [Proof-General](https://proofgeneral.github.io/) (and optionally + [Company-Coq](https://github.com/cpitclaudel/company-coq)) instead. + If your use case is not covered by these alternative Emacs modes, + please open an issue. We can help set up external maintenance as part + of Proof-General, or independently as part of coq-community. + +Vernacular Commands + +- Removed deprecated commands `Arguments Scope` and `Implicit Arguments` + (not the option). Use the `Arguments` command instead. +- Nested proofs may be enabled through the option `Nested Proofs Allowed`. + By default, they are disabled and produce an error. The deprecation + warning which used to occur when using nested proofs has been removed. +- Added option `Uniform Inductive Parameters` which abstracts over parameters + before typechecking constructors, allowing to write for example + `Inductive list (A : Type) := nil : list | cons : A -> list -> list.` +- New `Set Hint Variables/Constants Opaque/Transparent` commands for setting + globally the opacity flag of variables and constants in hint databases, + overwritting the opacity set of the hint database. +- Added generic syntax for "attributes", as in: + `#[local] Lemma foo : bar.` +- Added the `Numeral Notation` command for registering decimal numeral + notations for custom types +- The `Set SsrHave NoTCResolution` command no longer has special global + scope. If you want the previous behavior, use `Global Set SsrHave + NoTCResolution`. +- Multiple sections with the same name are allowed. + +Coq binaries and process model + +- Before 8.9, Coq distributed a single `coqtop` binary and a set of + dynamically loadable plugins that used to take over the main loop + for tasks such as IDE language server or parallel proof checking. + + These plugins have been turned into full-fledged binaries so each + different process has associated a particular binary now, in + particular `coqidetop` is the CoqIDE language server, and + `coq{proof,tactic,query}worker` are in charge of task-specific and + parallel proof checking. + +SSReflect + +- The implementation of delayed clear switches in intro patterns + is now simpler to explain: + + 1. The immediate effect of a clear switch like `{x}` is to rename the + variable `x` to `_x_` (i.e. a reserved identifier that cannot be mentioned + explicitly) + 2. The delayed effect of `{x}` is that `_x_` is cleared at the end of the intro + pattern + 3. A clear switch immediately before a view application like `{x}/v` is + translated to `/v{x}`. + + In particular, the third rule lets one write `{x}/v` even if `v` uses the variable `x`: + indeed the view is executed before the renaming. + +- An empty clear switch is now accepted in intro patterns before a + view application whenever the view is a variable. + One can now write `{}/v` to mean `{v}/v`. Remark that `{}/x` is very similar + to the idiom `{}e` for the rewrite tactic (the equation `e` is used for + rewriting and then discarded). + +Standard Library + +- There are now conversions between `string` and `positive`, `Z`, + `nat`, and `N` in binary, octal, and hex. + +Display diffs between proof steps + +- `coqtop` and `coqide` can now highlight the differences between proof steps + in color. This can be enabled from the command line or the + `Set Diffs "on"/"off"/"removed"` command. Please see the documentation for + details. Showing diffs in Proof General requires small changes to PG + (under discussion). + +Notations + +- Added `++` infix for `VectorDef.append`. + Note that this might cause incompatibilities if you have, e.g., `list_scope` + and `vector_scope` both open with `vector_scope` on top, and expect `++` to + refer to `app`. + Solution: wrap `_ ++ _` in `(_ ++ _)%list` (or whichever scope you want). + +Version 8.8 +----------- + +Summary of changes +~~~~~~~~~~~~~~~~~~ + +|Coq| version 8.8 contains the result of refinements and stabilization of +features and deprecations, cleanups of the internals of the system along +with a few new features. The main user visible changes are: + +- Kernel: fix a subject reduction failure due to allowing fixpoints + on non-recursive values, by Matthieu Sozeau. + Handling of evars in the VM (the kernel still does not accept evars) + by Pierre-Marie Pédrot. + +- Notations: many improvements on recursive notations and support for + destructuring patterns in the syntax of notations by Hugo Herbelin. + +- Proof language: tacticals for profiling, timing and checking success + or failure of tactics by Jason Gross. The focusing bracket ``{`` + supports single-numbered goal selectors, e.g. ``2:{``, by Théo + Zimmermann. + +- Vernacular: deprecation of commands and more uniform handling of the + ``Local`` flag, by Vincent Laporte and Maxime Dénès, part of a larger + attribute system overhaul. Experimental ``Show Extraction`` command by + Pierre Letouzey. Coercion now accepts ``Prop`` or ``Type`` as a source + by Arthur Charguéraud. ``Export`` modifier for options allowing to + export the option to modules that ``Import`` and not only ``Require`` + a module, by Pierre-Marie Pédrot. + +- Universes: many user-level and API level enhancements: qualified + naming and printing, variance annotations for cumulative inductive + types, more general constraints and enhancements of the minimization + heuristics, interaction with modules by Gaëtan Gilbert, Pierre-Marie + Pédrot and Matthieu Sozeau. + +- Library: Decimal Numbers library by Pierre Letouzey and various small + improvements. + +- Documentation: a large community effort resulted in the migration + of the reference manual to the Sphinx documentation tool. The result + is this manual. The new documentation infrastructure (based on Sphinx) + is by Clément Pit-Claudel. The migration was coordinated by Maxime Dénès + and Paul Steckler, with some help of Théo Zimmermann during the + final integration phase. The 14 people who ported the manual are + Calvin Beck, Heiko Becker, Yves Bertot, Maxime Dénès, Richard Ford, + Pierre Letouzey, Assia Mahboubi, Clément Pit-Claudel, + Laurence Rideau, Matthieu Sozeau, Paul Steckler, Enrico Tassi, + Laurent Théry, Nikita Zyuzin. + +- Tools: experimental ``-mangle-names`` option to ``coqtop``/``coqc`` for + linting proof scripts, by Jasper Hugunin. + +On the implementation side, the ``dev/doc/changes.md`` file +documents the numerous changes to the implementation and improvements of +interfaces. The file provides guidelines on porting a plugin to the new +version. + +Version 8.8 also comes with a bunch of smaller-scale changes and +improvements regarding the different components of the system. +Most important ones are documented in the ``CHANGES.md`` file. + +The efficiency of the whole system has seen improvements thanks to +contributions from Gaëtan Gilbert, Pierre-Marie Pédrot, Maxime Dénès and +Matthieu Sozeau and performance issue tracking by Jason Gross and Paul +Steckler. + +The official wiki and the bugtracker of |Coq| migrated to the GitHub +platform, thanks to the work of Pierre Letouzey and Théo +Zimmermann. Gaëtan Gilbert, Emilio Jesús Gallego Arias worked on +maintaining and improving the continuous integration system. + +The OPAM repository for |Coq| packages has been maintained by Guillaume +Melquiond, Matthieu Sozeau, Enrico Tassi with contributions from many +users. A list of packages is available at https://coq.inria.fr/opam/www/. + +The 44 contributors for this version are Yves Bertot, Joachim Breitner, Tej +Chajed, Arthur Charguéraud, Jacques-Pascal Deplaix, Maxime Dénès, Jim Fehrle, +Julien Forest, Yannick Forster, Gaëtan Gilbert, Jason Gross, Samuel Gruetter, +Thomas Hebb, Hugo Herbelin, Jasper Hugunin, Emilio Jesus Gallego Arias, Ralf +Jung, Johannes Kloos, Matej Košík, Robbert Krebbers, Tony Beta Lambda, Vincent +Laporte, Peter LeFanu Lumsdaine, Pierre Letouzey, Farzon Lotfi, Cyprien Mangin, +Guillaume Melquiond, Raphaël Monat, Carl Patenaude Poulin, Pierre-Marie Pédrot, +Clément Pit-Claudel, Matthew Ryan, Matt Quinn, Sigurd Schneider, Bernhard +Schommer, Michael Soegtrop, Matthieu Sozeau, Arnaud Spiwack, Paul Steckler, +Enrico Tassi, Anton Trunov, Martin Vassor, Vadim Zaliva and Théo Zimmermann. + +Version 8.8 is the third release of |Coq| developed on a time-based +development cycle. Its development spanned 6 months from the release of +|Coq| 8.7 and was based on a public roadmap. The development process +was coordinated by Matthieu Sozeau. Maxime Dénès was in charge of the +release process. Théo Zimmermann is the maintainer of this release. + +Many power users helped to improve the design of the new features via +the bug tracker, the pull request system, the |Coq| development mailing +list or the coq-club@inria.fr mailing list. Special thanks to the users who +contributed patches and intensive brain-storming and code reviews, +starting with Jason Gross, Ralf Jung, Robbert Krebbers and Amin Timany. +It would however be impossible to mention exhaustively the names +of everybody who to some extent influenced the development. + +The |Coq| consortium, an organization directed towards users and +supporters of the system, is now running and employs Maxime Dénès. +The contacts of the Coq Consortium are Yves Bertot and Maxime Dénès. + +| Santiago de Chile, March 2018, +| Matthieu Sozeau for the |Coq| development team +| + +Details of changes in 8.8+beta1 +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Kernel + +- Support for template polymorphism for definitions was removed. May trigger + more "universe inconsistency" errors in rare occasions. +- Fixpoints are no longer allowed on non-recursive inductive types. + +Notations + +- Recursive notations with the recursive pattern repeating on the + right (e.g. "( x ; .. ; y ; z )") now supported. +- Notations with a specific level for the leftmost nonterminal, + when printing-only, are supported. +- Notations can now refer to the syntactic category of patterns (as in + "fun 'pat =>" or "match p with pat => ... end"). Two variants are + available, depending on whether a single variable is considered as a + pattern or not. +- Recursive notations now support ".." patterns with several + occurrences of the recursive term or binder, possibly mixing terms + and binders, possibly in reverse left-to-right order. +- "Locate" now working also on notations of the form "x + y" (rather + than "_ + _"). + +Specification language + +- When printing clauses of a "match", clauses with same right-hand + side are factorized and the last most factorized clause with no + variables, if it exists, is turned into a default clause. + Use "Unset Printing Allow Default Clause" do deactivate printing + of a default clause. + Use "Unset Printing Factorizable Match Patterns" to deactivate + factorization of clauses with same right-hand side. + +Tactics + +- On Linux, "native_compute" calls can be profiled using the "perf" + utility. The command "Set NativeCompute Profiling" enables + profiling, and "Set NativeCompute Profile Filename" customizes + the profile filename. +- The tactic "omega" is now aware of the bodies of context variables + such as "x := 5 : Z" (see #1362). This could be disabled via + Unset Omega UseLocalDefs. +- The tactic "romega" is also aware now of the bodies of context variables. +- The tactic "zify" resp. "omega with N" is now aware of N.pred. +- Tactic "decide equality" now able to manage constructors which + contain proofs. +- Added tactics reset ltac profile, show ltac profile (and variants) +- Added tactics restart_timer, finish_timing, and time_constr as an + experimental way of timing Ltac's evaluation phase +- Added tactic optimize_heap, analogous to the Vernacular Optimize + Heap, which performs a major garbage collection and heap compaction + in the OCaml run-time system. +- The tactics "dtauto", "dintuition", "firstorder" now handle inductive types + with let bindings in the parameters. +- The tactic ``dtauto`` now handles some inductives such as + ``@sigT A (fun _ => B)`` as non-dependent conjunctions. +- A bug fixed in ``rewrite H in *`` and ``rewrite H in * |-`` may cause a + few rare incompatibilities (it was unintendedly recursively + rewriting in the side conditions generated by H). +- Added tactics "assert_succeeds tac" and "assert_fails tac" to ensure + properties of the executation of a tactic without keeping the effect + of the execution. +- `vm_compute` now supports existential variables. +- Calls to `shelve` and `give_up` within calls to tactic `refine` now working. +- Deprecated tactic `appcontext` was removed. + +Focusing + +- Focusing bracket `{` now supports single-numbered goal selector, + e.g. `2: {` will focus on the second sub-goal. As usual, unfocus + with `}` once the sub-goal is fully solved. + The `Focus` and `Unfocus` commands are now deprecated. + +Vernacular Commands + +- Proofs ending in "Qed exporting ident, .., ident" are not supported + anymore. Constants generated during `abstract` are kept private to the + local environment. +- The deprecated Coercion Local, Open Local Scope, Notation Local syntax + was removed. Use Local as a prefix instead. +- For the Extraction Language command, "OCaml" is spelled correctly. + The older "Ocaml" is still accepted, but deprecated. +- Using “Require” inside a section is deprecated. +- An experimental command "Show Extraction" allows to extract the content + of the current ongoing proof (grant wish #4129). +- Coercion now accepts the type of its argument to be "Prop" or "Type". +- The "Export" modifier can now be used when setting and unsetting options, and + will result in performing the same change when the module corresponding the + command is imported. +- The `Axiom` command does not automatically declare axioms as instances when + their type is a class. Previous behavior can be restored using `Set + Typeclasses Axioms Are Instances`. + +Universes + +- Qualified naming of global universes now works like other namespaced + objects (e.g. constants), with a separate namespace, inside and across + module and library boundaries. Global universe names introduced in an + inductive / constant / Let declaration get qualified with the name of + the declaration. +- Universe cumulativity for inductive types is now specified as a + variance for each polymorphic universe. See the reference manual for + more information. +- Inference of universe constraints with cumulative inductive types + produces more general constraints. Unsetting new option Cumulativity + Weak Constraints produces even more general constraints (but may + produce too many universes to be practical). +- Fix #5726: Notations that start with `Type` now support universe instances + with `@{u}`. +- `with Definition` now understands universe declarations + (like `@{u| Set < u}`). + +Tools + +- Coq can now be run with the option -mangle-names to change the auto-generated + name scheme. This is intended to function as a linter for developments that + want to be robust to changes in auto-generated names. This feature is experimental, + and may change or disappear without warning. +- GeoProof support was removed. + +Checker + +- The checker now accepts filenames in addition to logical paths. + +CoqIDE + +- Find and Replace All report the number of occurrences found; Find indicates + when it wraps. + +coqdep + +- Learned to read -I, -Q, -R and filenames from _CoqProject files. + This is used by coq_makefile when generating dependencies for .v + files (but not other files). + +Documentation + +- The Coq FAQ, formerly located at https://coq.inria.fr/faq, has been + moved to the GitHub wiki section of this repository; the main entry + page is https://github.com/coq/coq/wiki/The-Coq-FAQ. +- Documentation: a large community effort resulted in the migration + of the reference manual to the Sphinx documentation tool. The result + is partially integrated in this version. + +Standard Library + +- New libraries Coq.Init.Decimal, Coq.Numbers.DecimalFacts, + Coq.Numbers.DecimalNat, Coq.Numbers.DecimalPos, + Coq.Numbers.DecimalN, Coq.Numbers.DecimalZ, + Coq.Numbers.DecimalString providing a type of decimal numbers, some + facts about them, and conversions between decimal numbers and nat, + positive, N, Z, and string. +- Added [Coq.Strings.String.concat] to concatenate a list of strings + inserting a separator between each item +- Notation `'` for Zpos in QArith was removed. + +- Some deprecated aliases are now emitting warnings when used. + +Compatibility support + +- Support for compatibility with versions before 8.6 was dropped. + +Options + +- The following deprecated options have been removed: + + + `Refolding Reduction` + + `Standard Proposition Elimination` + + `Dependent Propositions Elimination` + + `Discriminate Introduction` + + `Shrink Abstract` + + `Tactic Pattern Unification` + + `Intuition Iff Unfolding` + + `Injection L2R Pattern Order` + + `Record Elimination Schemes` + + `Match Strict` + + `Tactic Compat Context` + + `Typeclasses Legacy Resolution` + + `Typeclasses Module Eta` + + `Typeclass Resolution After Apply` + +Details of changes in 8.8.0 +~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Tools + +- Asynchronous proof delegation policy was fixed. Since version 8.7 + Coq was ignoring previous runs and the `-async-proofs-delegation-threshold` + option did not have the expected behavior. + +Tactic language + +- The undocumented "nameless" forms `fix N`, `cofix` have been + deprecated; please use `fix ident N /cofix ident` to explicitely + name the (co)fixpoint hypothesis to be introduced. + +Documentation + +- The reference manual is now fully ported to Sphinx. + +Other small deprecations and bug fixes. + +Details of changes in 8.8.1 +~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Kernel + +- Fix a critical bug with cofixpoints and `vm_compute`/`native_compute` (#7333). +- Fix a critical bug with modules and algebraic universes (#7695) +- Fix a critical bug with inlining of polymorphic constants (#7615). +- Fix a critical bug with universe polymorphism and `vm_compute` (#7723). Was + present since 8.5. + +Notations + +- Fixed unexpected collision between only-parsing and only-printing + notations (issue #7462). + +Windows installer + +- The Windows installer now includes external packages Ltac2 and Equations + (it included the Bignums package since 8.8+beta1). + +Many other bug fixes, documentation improvements (including fixes of +regressions due to the Sphinx migration), and user message improvements +(for details, see the 8.8.1 milestone at +https://github.com/coq/coq/milestone/13?closed=1). + +Details of changes in 8.8.2 +~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Documentation + +- A PDF version of the reference manual is available once again. + +Tools + +- The coq-makefile targets `print-pretty-timed`, `print-pretty-timed-diff`, + and `print-pretty-single-time-diff` now correctly label the "before" and + "after" columns, rather than swapping them. + +Kernel + +- The kernel does not tolerate capture of global universes by + polymorphic universe binders, fixing a soundness break (triggered + only through custom plugins) + +Windows installer + +- The Windows installer now includes many more external packages that can be + individually selected for installation. + +Many other bug fixes and lots of documentation improvements (for details, +see the 8.8.2 milestone at https://github.com/coq/coq/milestone/15?closed=1). + +Version 8.7 +----------- + +Summary of changes +~~~~~~~~~~~~~~~~~~ + +|Coq| version 8.7 contains the result of refinements, stabilization of features +and cleanups of the internals of the system along with a few new features. The +main user visible changes are: + +- New tactics: variants of tactics supporting existential variables :tacn:`eassert`, + :tacn:`eenough`, etc... by Hugo Herbelin. Tactics ``extensionality in H`` and + :tacn:`inversion_sigma` by Jason Gross, ``specialize with ...`` accepting partial bindings + by Pierre Courtieu. + +- ``Cumulative Polymorphic Inductive`` types, allowing cumulativity of universes to + go through applied inductive types, by Amin Timany and Matthieu Sozeau. + +- Integration of the SSReflect plugin and its documentation in the reference + manual, by Enrico Tassi, Assia Mahboubi and Maxime Dénès. + +- The ``coq_makefile`` tool was completely redesigned to improve its maintainability + and the extensibility of generated Makefiles, and to make ``_CoqProject`` files + more palatable to IDEs by Enrico Tassi. + +|Coq| 8.7 involved a large amount of work on cleaning and speeding up the code +base, notably the work of Pierre-Marie Pédrot on making the tactic-level system +insensitive to existential variable expansion, providing a safer API to plugin +writers and making the code more robust. The ``dev/doc/changes.txt`` file +documents the numerous changes to the implementation and improvements of +interfaces. An effort to provide an official, streamlined API to plugin writers +is in progress, thanks to the work of Matej Košík. + +Version 8.7 also comes with a bunch of smaller-scale changes and improvements +regarding the different components of the system. We shall only list a few of +them. + +The efficiency of the whole system has been significantly improved thanks to +contributions from Pierre-Marie Pédrot, Maxime Dénès and Matthieu Sozeau and +performance issue tracking by Jason Gross and Paul Steckler. + +Thomas Sibut-Pinote and Hugo Herbelin added support for side effect hooks in +cbv, cbn and simpl. The side effects are provided via a plugin available at +https://github.com/herbelin/reduction-effects/. + +The BigN, BigZ, BigQ libraries are no longer part of the |Coq| standard library, +they are now provided by a separate repository https://github.com/coq/bignums, +maintained by Pierre Letouzey. + +In the Reals library, ``IZR`` has been changed to produce a compact representation +of integers and real constants are now represented using ``IZR`` (work by +Guillaume Melquiond). + +Standard library additions and improvements by Jason Gross, Pierre Letouzey and +others, documented in the ``CHANGES.md`` file. + +The mathematical proof language/declarative mode plugin was removed from the +archive. + +The OPAM repository for |Coq| packages has been maintained by Guillaume Melquiond, +Matthieu Sozeau, Enrico Tassi with contributions from many users. A list of +packages is available at https://coq.inria.fr/opam/www/. + +Packaging tools and software development kits were prepared by Michael Soegtrop +with the help of Maxime Dénès and Enrico Tassi for Windows, and Maxime Dénès for +MacOS X. Packages are regularly built on the Travis continuous integration +server. + +The contributors for this version are Abhishek Anand, C.J. Bell, Yves Bertot, +Frédéric Besson, Tej Chajed, Pierre Courtieu, Maxime Dénès, Julien Forest, +Gaëtan Gilbert, Jason Gross, Hugo Herbelin, Emilio Jesús Gallego Arias, Ralf +Jung, Matej Košík, Xavier Leroy, Pierre Letouzey, Assia Mahboubi, Cyprien +Mangin, Erik Martin-Dorel, Olivier Marty, Guillaume Melquiond, Sam Pablo Kuper, +Benjamin Pierce, Pierre-Marie Pédrot, Lars Rasmusson, Lionel Rieg, Valentin +Robert, Yann Régis-Gianas, Thomas Sibut-Pinote, Michael Soegtrop, Matthieu +Sozeau, Arnaud Spiwack, Paul Steckler, George Stelle, Pierre-Yves Strub, Enrico +Tassi, Hendrik Tews, Amin Timany, Laurent Théry, Vadim Zaliva and Théo +Zimmermann. + +The development process was coordinated by Matthieu Sozeau with the help of +Maxime Dénès, who was also in charge of the release process. Théo Zimmermann is +the maintainer of this release. + +Many power users helped to improve the design of the new features via the bug +tracker, the pull request system, the |Coq| development mailing list or the +Coq-Club mailing list. Special thanks to the users who contributed patches and +intensive brain-storming and code reviews, starting with Jason Gross, Ralf Jung, +Robbert Krebbers, Xavier Leroy, Clément Pit–Claudel and Gabriel Scherer. It +would however be impossible to mention exhaustively the names of everybody who +to some extent influenced the development. + +Version 8.7 is the second release of |Coq| developed on a time-based development +cycle. Its development spanned 9 months from the release of |Coq| 8.6 and was +based on a public road-map. It attracted many external contributions. Code +reviews and continuous integration testing were systematically used before +integration of new features, with an important focus given to compatibility and +performance issues, resulting in a hopefully more robust release than |Coq| 8.6 +while maintaining compatibility. + +|Coq| Enhancement Proposals (CEPs for short) and open pull request discussions +were used to discuss publicly the new features. + +The |Coq| consortium, an organization directed towards users and supporters of the +system, is now upcoming and will rely on Inria’s newly created Foundation. + +| Paris, August 2017, +| Matthieu Sozeau and the |Coq| development team +| + +Potential compatibility issues +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +- Extra superfluous names in introduction patterns may now raise an + error rather than a warning when the superfluous name is already in + use. The easy fix is to remove the superfluous name. + +Details of changes in 8.7+beta1 +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Tactics + +- New tactic "extensionality in H" which applies (possibly dependent) + functional extensionality in H supposed to be a quantified equality + until giving a bare equality. + +- New tactic ``inversion_sigma`` which turns equalities of dependent + pairs (e.g., ``existT P x p = existT P y q``, frequently left over by + ``inversion`` on a dependent type family) into pairs of equalities + (e.g., a hypothesis ``H : x = y`` and a hypothesis of type ``rew H in p = q``); + these hypotheses can subsequently be simplified using + ``subst``, without ever invoking any kind of axiom asserting + uniqueness of identity proofs. If you want to explicitly specify the + hypothesis to be inverted, or name the generated hypotheses, you can + invoke ``induction H as [H1 H2] using eq_sigT_rect``. The tactic also + works for ``sig``, ``sigT2``, and ``sig2``, and there are similar + ``eq_sig*_rect`` induction lemmas. + +- Tactic "specialize with ..." now accepts any partial bindings. + Missing bindings are either solved by unification or left quantified + in the hypothesis. + +- New representation of terms that statically ensure stability by + evar-expansion. This has several consequences. + + * In terms of performance, this adds a cost to every term destructuration, + but at the same time most eager evar normalizations were removed, which + couterbalances this drawback and even sometimes outperforms the old + implementation. For instance, many operations that would require O(n) + normalization of the term are now O(1) in tactics. YMMV. + + * This triggers small changes in unification, which was not evar-insensitive. + Most notably, the new implementation recognizes Miller patterns that were + missed before because of a missing normalization step. Hopefully this should + be fairly uncommon. + +- Tactic "auto with real" can now discharge comparisons of literals. + +- The types of variables in patterns of "match" are now + beta-iota-reduced after type-checking. This has an impact on the + type of the variables that the tactic "refine" introduces in the + context, producing types a priori closer to the expectations. + +- In "Tactic Notation" or "TACTIC EXTEND", entry "constr_with_bindings" + now uses type classes and rejects terms with unresolved holes, like + entry "constr" does. To get the former behavior use + "open_constr_with_bindings" (possible source of incompatibility). + +- New e-variants eassert, eenough, epose proof, eset, eremember, epose + which behave like the corresponding variants with no "e" but turn + unresolved implicit arguments into existential variables, on the + shelf, rather than failing. + +- Tactic injection has become more powerful (closes bug #4890) and its + documentation has been updated. + +- New variants of the `first` and `solve` tacticals that do not rely + on parsing rules, meant to define tactic notations. + +- Added support for side effects hooks in `cbv`, `cbn` and `simpl`. + The side effects are provided via a plugin: + https://github.com/herbelin/reduction-effects/ + +- It is now possible to take hint database names as parameters in a + Ltac definition or a Tactic Notation. + +- New option `Set Ltac Batch Debug` on top of `Set Ltac Debug` for + non-interactive Ltac debug output. + +Gallina + +- Now supporting all kinds of binders, including 'pat, in syntax of record fields. + +Vernacular Commands + +- Goals context can be printed in a more compact way when `Set + Printing Compact Contexts` is activated. +- Unfocused goals can be printed with the `Set Printing Unfocused` + option. +- `Print` now shows the types of let-bindings. +- The compatibility options for printing primitive projections + (`Set Printing Primitive Projection Parameters` and + `Set Printing Primitive Projection Compatibility`) are now off by default. +- Possibility to unset the printing of notations in a more fine grained + fashion than `Unset Printing Notations` is provided without any + user-syntax. The goal is that someone creates a plugin to experiment + such a user-syntax, to be later integrated in Coq when stabilized. +- `About` now tells if a reference is a coercion. +- The deprecated `Save` vernacular and its form `Save Theorem id` to + close proofs have been removed from the syntax. Please use `Qed`. +- `Search` now sorts results by relevance (the relevance metric is a + weighted sum of number of distinct symbols and size of the term). + +Standard Library + +- New file PropExtensionality.v to explicitly work in the axiomatic + context of propositional extensionality. +- New file SetoidChoice.v axiomatically providing choice over setoids, + and, consequently, choice of representatives in equivalence classes. + Various proof-theoretic characterizations of choice over setoids in + file ChoiceFacts.v. +- New lemmas about iff and about orders on positive and Z. +- New lemmas on powerRZ. +- Strengthened statement of JMeq_eq_dep (closes bug #4912). +- The BigN, BigZ, BigZ libraries are no longer part of the Coq standard + library, they are now provided by a separate repository + https://github.com/coq/bignums + The split has been done just after the Int31 library. + +- IZR (Reals) has been changed to produce a compact representation of + integers. As a consequence, IZR is no longer convertible to INR and + lemmas such as INR_IZR_INZ should be used instead. +- Real constants are now represented using IZR rather than R0 and R1; + this might cause rewriting rules to fail to apply to constants. +- Added new notation {x & P} for sigT (without a type for x) + +Plugins + +- The Ssreflect plugin is now distributed with Coq. Its documentation has + been integrated as a chapter of the reference manual. This chapter is + work in progress so feedback is welcome. +- The mathematical proof language (also known as declarative mode) was removed. +- A new command Extraction TestCompile has been introduced, not meant + for the general user but instead for Coq's test-suite. +- The extraction plugin is no longer loaded by default. It must be + explicitly loaded with [Require Extraction], which is backwards + compatible. +- The functional induction plugin (which provides the [Function] + vernacular) is no longer loaded by default. It must be explicitly + loaded with [Require FunInd], which is backwards compatible. + + +Dependencies + +- Support for camlp4 has been removed. + +Tools + +- coq_makefile was completely redesigned to improve its maintainability and + the extensibility of generated Makefiles, and to make _CoqProject files + more palatable to IDEs. Overview: + + * _CoqProject files contain only Coq specific data (i.e. the list of + files, -R options, ...) + * coq_makefile translates _CoqProject to Makefile.conf and copies in the + desired location a standard Makefile (that reads Makefile.conf) + * Makefile extensions can be implemented in a Makefile.local file (read + by the main Makefile) by installing a hook in the extension points + provided by the standard Makefile + + The current version contains code for retro compatibility that prints + warnings when a deprecated feature is used. Please upgrade your _CoqProject + accordingly. + + * Additionally, coq_makefile-made Makefiles now support experimental timing + targets `pretty-timed`, `pretty-timed-before`, `pretty-timed-after`, + `print-pretty-timed-diff`, `print-pretty-single-time-diff`, + `all.timing.diff`, and the variable `TIMING=1` (or `TIMING=before` or + `TIMING=after`); see the documentation for more details. + +Build Infrastructure + +- Note that 'make world' does not build the bytecode binaries anymore. + For that, you can use 'make byte' (and 'make install-byte' afterwards). + Warning: native and byte compilations should *not* be mixed in the same + instance of 'make -j', otherwise both ocamlc and ocamlopt might race for + access to the same .cmi files. In short, use "make -j && make -j byte" + instead of "make -j world byte". + +Universes + +- Cumulative inductive types. see prefixes "Cumulative", "NonCumulative" + for inductive definitions and the option "Set Polymorphic Inductive Cumulativity" + in the reference manual. +- New syntax `foo@{_}` to instantiate a polymorphic definition with + anonymous universes (can also be used with `Type`). + +XML Protocol and internal changes + +See dev/doc/changes.txt + +Many bugfixes including #1859, #2884, #3613, #3943, #3994, +#4250, #4709, #4720, #4824, #4844, #4911, #5026, #5233, +#5275, #5315, #5336, #5360, #5390, #5414, #5417, #5420, +#5439, #5449, #5475, #5476, #5482, #5501, #5507, #5520, +#5523, #5524, #5553, #5577, #5578, #5589, #5597, #5598, +#5607, #5618, #5619, #5620, #5641, #5648, #5651, #5671. + +Many bugfixes on OS X and Windows (now the test-suite passes on these +platforms too). + +Many optimizations. + +Many documentation improvements. + +Details of changes in 8.7+beta2 +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Tools + +- In CoqIDE, the "Compile Buffer" command takes account of flags in + _CoqProject or other project file. + +Improvements around some error messages. + +Many bug fixes including two important ones: + +- Bug #5730: CoqIDE becomes unresponsive on file open. +- coq_makefile: make sure compile flags for Coq and coq_makefile are in sync + (in particular, make sure the `-safe-string` option is used to compile plugins). + +Details of changes in 8.7.0 +~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +OCaml + +- Users can pass specific flags to the OCaml optimizing compiler by + -using the flambda-opts configure-time option. + + Beware that compiling Coq with a flambda-enabled compiler is + experimental and may require large amounts of RAM and CPU, see + INSTALL for more details. + +Details of changes in 8.7.1 +~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Compatibility with OCaml 4.06.0. + +Many bug fixes, documentation improvements, and user message improvements (for +details see the 8.7.1 milestone at https://github.com/coq/coq/milestone/10?closed=1). + +Details of changes in 8.7.2 +~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Fixed a critical bug in the VM handling of universes (#6677). This bug +affected all releases since 8.5. + +Improved support for building with OCaml 4.06.0 and external num package. + +Many other bug fixes, documentation improvements, and user +message improvements (for details, see the 8.7.2 milestone at +https://github.com/coq/coq/milestone/11?closed=1). + +Version 8.6 +----------- + +Summary of changes +~~~~~~~~~~~~~~~~~~ + +Coq version 8.6 contains the result of refinements, stabilization of +8.5’s features and cleanups of the internals of the system. Over the +year of (now time-based) development, about 450 bugs were resolved and +over 100 contributions integrated. The main user visible changes are: + +- A new, faster state-of-the-art universe constraint checker, by + Jacques-Henri Jourdan. + +- In |CoqIDE| and other asynchronous interfaces, more fine-grained + asynchronous processing and error reporting by Enrico Tassi, making + |Coq| capable of recovering from errors and continue processing the + document. + +- More access to the proof engine features from Ltac: goal management + primitives, range selectors and a :tacn:`typeclasses eauto` engine handling + multiple goals and multiple successes, by Cyprien Mangin, Matthieu + Sozeau and Arnaud Spiwack. + +- Tactic behavior uniformization and specification, generalization of + intro-patterns by Hugo Herbelin and others. + +- A brand new warning system allowing to control warnings, turn them + into errors or ignore them selectively by Maxime Dénès, Guillaume + Melquiond, Pierre-Marie Pédrot and others. + +- Irrefutable patterns in abstractions, by Daniel de Rauglaudre. + +- The ssreflect subterm selection algorithm by Georges Gonthier and + Enrico Tassi is now accessible to tactic writers through the + ssrmatching plugin. + +- Integration of LtacProf, a profiler for Ltac by Jason Gross, Paul + Steckler, Enrico Tassi and Tobias Tebbi. + +Coq 8.6 also comes with a bunch of smaller-scale changes and +improvements regarding the different components of the system. We shall +only list a few of them. + +The iota reduction flag is now a shorthand for match, fix and cofix +flags controlling the corresponding reduction rules (by Hugo Herbelin +and Maxime Dénès). + +Maxime Dénès maintained the native compilation machinery. + +Pierre-Marie Pédrot separated the Ltac code from general purpose +tactics, and generalized and rationalized the handling of generic +arguments, allowing to create new versions of Ltac more easily in the +future. + +In patterns and terms, @, abbreviations and notations are now +interpreted the same way, by Hugo Herbelin. + +Name handling for universes has been improved by Pierre-Marie Pédrot and +Matthieu Sozeau. The minimization algorithm has been improved by +Matthieu Sozeau. + +The unifier has been improved by Hugo Herbelin and Matthieu Sozeau, +fixing some incompatibilities introduced in |Coq| 8.5. Unification +constraints can now be left floating around and be seen by the user +thanks to a new option. The Keyed Unification mode has been improved by +Matthieu Sozeau. + +The typeclass resolution engine and associated proof-search tactic have +been reimplemented on top of the proof-engine monad, providing better +integration in tactics, and new options have been introduced to control +it, by Matthieu Sozeau with help from Théo Zimmermann. + +The efficiency of the whole system has been significantly improved +thanks to contributions from Pierre-Marie Pédrot, Maxime Dénès and +Matthieu Sozeau and performance issue tracking by Jason Gross and Paul +Steckler. + +Standard library improvements by Jason Gross, Sébastien Hinderer, Pierre +Letouzey and others. + +Emilio Jesús Gallego Arias contributed many cleanups and refactorings of +the pretty-printing and user interface communication components. + +Frédéric Besson maintained the micromega tactic. + +The OPAM repository for |Coq| packages has been maintained by Guillaume +Claret, Guillaume Melquiond, Matthieu Sozeau, Enrico Tassi and others. A +list of packages is now available at https://coq.inria.fr/opam/www/. + +Packaging tools and software development kits were prepared by Michael +Soegtrop with the help of Maxime Dénès and Enrico Tassi for Windows, and +Maxime Dénès and Matthieu Sozeau for MacOS X. Packages are now regularly +built on the continuous integration server. |Coq| now comes with a META +file usable with ocamlfind, contributed by Emilio Jesús Gallego Arias, +Gregory Malecha, and Matthieu Sozeau. + +Matej Košík maintained and greatly improved the continuous integration +setup and the testing of |Coq| contributions. He also contributed many API +improvements and code cleanups throughout the system. + +The contributors for this version are Bruno Barras, C.J. Bell, Yves +Bertot, Frédéric Besson, Pierre Boutillier, Tej Chajed, Guillaume +Claret, Xavier Clerc, Pierre Corbineau, Pierre Courtieu, Maxime Dénès, +Ricky Elrod, Emilio Jesús Gallego Arias, Jason Gross, Hugo Herbelin, +Sébastien Hinderer, Jacques-Henri Jourdan, Matej Košík, Xavier Leroy, +Pierre Letouzey, Gregory Malecha, Cyprien Mangin, Erik Martin-Dorel, +Guillaume Melquiond, Clément Pit–Claudel, Pierre-Marie Pédrot, Daniel de +Rauglaudre, Lionel Rieg, Gabriel Scherer, Thomas Sibut-Pinote, Matthieu +Sozeau, Arnaud Spiwack, Paul Steckler, Enrico Tassi, Laurent Théry, +Nickolai Zeldovich and Théo Zimmermann. The development process was +coordinated by Hugo Herbelin and Matthieu Sozeau with the help of Maxime +Dénès, who was also in charge of the release process. + +Many power users helped to improve the design of the new features via +the bug tracker, the pull request system, the |Coq| development mailing +list or the Coq-Club mailing list. Special thanks to the users who +contributed patches and intensive brain-storming and code reviews, +starting with Cyril Cohen, Jason Gross, Robbert Krebbers, Jonathan +Leivent, Xavier Leroy, Gregory Malecha, Clément Pit–Claudel, Gabriel +Scherer and Beta Ziliani. It would however be impossible to mention +exhaustively the names of everybody who to some extent influenced the +development. + +Version 8.6 is the first release of |Coq| developed on a time-based +development cycle. Its development spanned 10 months from the release of +Coq 8.5 and was based on a public roadmap. To date, it contains more +external contributions than any previous |Coq| system. Code reviews were +systematically done before integration of new features, with an +important focus given to compatibility and performance issues, resulting +in a hopefully more robust release than |Coq| 8.5. + +Coq Enhancement Proposals (CEPs for short) were introduced by Enrico +Tassi to provide more visibility and a discussion period on new +features, they are publicly available https://github.com/coq/ceps. + +Started during this period, an effort is led by Yves Bertot and Maxime +Dénès to put together a |Coq| consortium. + +| Paris, November 2016, +| Matthieu Sozeau and the |Coq| development team +| + +Potential sources of incompatibilities +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +- Symptom: An obligation generated by Program or an abstracted subproof + has different arguments. + + Cause: Set Shrink Abstract and Set Shrink Obligations are on by default + and the subproof does not use the argument. + + Remedy: + + + Adapt the script. + + Write an explicit lemma to prove the obligation/subproof and use it + instead (compatible with 8.4). + + Unset the option for the program/proof the obligation/subproof originates + from. + +- Symptom: In a goal, order of hypotheses, or absence of an equality of + the form "x = t" or "t = x", or no unfolding of a local definition. + + Cause: This might be connected to a number of fixes in the tactic + "subst". The former behavior can be reactivated by issuing "Unset + Regular Subst Tactic". + +Details of changes in 8.6beta1 +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Kernel + +- A new, faster state-of-the-art universe constraint checker. + +Specification language + +- Giving implicit arguments explicitly to a constant with multiple + choices of implicit arguments does not break any more insertion of + further maximal implicit arguments. +- Ability to put any pattern in binders, prefixed by quote, e.g. + "fun '(a,b) => ...", "λ '(a,(b,c)), ...", "Definition foo '(x,y) := ...". + It expands into a "let 'pattern := ..." + +Tactics + +- Flag "Bracketing Last Introduction Pattern" is now on by default. +- Flag "Regular Subst Tactic" is now on by default: it respects the + initial order of hypothesis, it contracts cycles, it unfolds no + local definitions (common source of incompatibilities, fixable by + "Unset Regular Subst Tactic"). +- New flag "Refolding Reduction", now disabled by default, which turns + on refolding of constants/fixpoints (as in cbn) during the reductions + done during type inference and tactic retyping. Can be extremely + expensive. When set off, this recovers the 8.4 behaviour of unification + and type inference. Potential source of incompatibility with 8.5 developments + (the option is set on in Compat/Coq85.v). +- New flag "Shrink Abstract" that minimalizes proofs generated by the abstract + tactical w.r.t. variables appearing in the body of the proof. + On by default and deprecated. Minor source of incompatibility + for code relying on the precise arguments of abstracted proofs. +- Serious bugs are fixed in tactic "double induction" (source of + incompatibilities as soon as the inductive types have dependencies in + the type of their constructors; "double induction" remains however + deprecated). +- In introduction patterns of the form (pat1,...,patn), n should match + the exact number of hypotheses introduced (except for local definitions + for which pattern can be omitted, as in regular pattern-matching). +- Tactic scopes in Ltac like constr: and ltac: now require parentheses around + their argument. +- Every generic argument type declares a tactic scope of the form "name:(...)" + where name is the name of the argument. This generalizes the constr: and ltac: + instances. +- When in strict mode (i.e. in a Ltac definition), if the "intro" tactic is + given a free identifier, it is not bound in subsequent tactics anymore. + In order to introduce a binding, use e.g. the "fresh" primitive instead + (potential source of incompatibilities). +- New tactics is_ind, is_const, is_proj, is_constructor for use in Ltac. +- New goal selectors. Sets of goals can be selected by listing integers + ranges. Example: "1,4-7,24: tac" focuses "tac" on goals 1,4,5,6,7,24. +- For uniformity with "destruct"/"induction" and for a more natural + behavior, "injection" can now work in place by activating option + "Structural Injection". In this case, hypotheses are also put in the + context in the natural left-to-right order and the hypothesis on + which injection applies is cleared. +- Tactic "contradiction" (hence "easy") now also solve goals with + hypotheses of the form "~True" or "t<>t" (possible source of + incompatibilities because of more successes in automation, but + generally a more intuitive strategy). +- Option "Injection On Proofs" was renamed "Keep Proof Equalities". When + enabled, injection and inversion do not drop equalities between objects + in Prop. Still disabled by default. +- New tactics "notypeclasses refine" and "simple notypeclasses refine" that + disallow typeclass resolution when typechecking their argument, for use + in typeclass hints. +- Integration of LtacProf, a profiler for Ltac. +- Reduction tactics now accept more fine-grained flags: iota is now a shorthand + for the new flags match, fix and cofix. +- The ssreflect subterm selection algorithm is now accessible to tactic writers + through the ssrmatching plugin. +- When used as an argument of an ltac function, "auto" without "with" + nor "using" clause now correctly uses only the core hint database by + default. + +Hints + +- Revised the syntax of [Hint Cut] to follow standard notation for regexps. +- Hint Mode now accepts "!" which means that the mode matches only if the + argument's head is not an evar (it goes under applications, casts, and + scrutinees of matches and projections). +- Hints can now take an optional user-given pattern, used only by + [typeclasses eauto] with the [Filtered Unification] option on. + +Typeclasses + +- Many new options and new engine based on the proof monad. The + [typeclasses eauto] tactic is now a multi-goal, multi-success tactic. + See reference manual for more information. It is planned to + replace auto and eauto in the following version. The 8.5 resolution + engine is still available to help solve compatibility issues. + +Program + +- The "Shrink Obligations" flag now applies to all obligations, not only + those solved by the automatic tactic. +- "Shrink Obligations" is on by default and deprecated. Minor source of + incompatibility for code relying on the precise arguments of + obligations. + +Notations + +- "Bind Scope" can once again bind "Funclass" and "Sortclass". + +General infrastructure + +- New configurable warning system which can be controlled with the vernacular + command "Set Warnings", or, under coqc/coqtop, with the flag "-w". In + particular, the default is now that warnings are printed by coqc. +- In asynchronous mode, Coq is now capable of recovering from errors and + continue processing the document. + +Tools + +- coqc accepts a -o option to specify the output file name +- coqtop accepts --print-version to print Coq and OCaml versions in + easy to parse format +- Setting [Printing Dependent Evars Line] can be unset to disable the + computation associated with printing the "dependent evars: " line in + -emacs mode +- Removed the -verbose-compat-notations flag and the corresponding Set + Verbose Compat vernacular, since these warnings can now be silenced or + turned into errors using "-w". + +XML protocol + +- message format has changed, see dev/doc/changes.txt for more details. + +Many bug fixes, minor changes and documentation improvements are not mentioned +here. + +Details of changes in 8.6 +~~~~~~~~~~~~~~~~~~~~~~~~~ + +Kernel + +- Fixed critical bug #5248 in VM long multiplication on 32-bit + architectures. Was there only since 8.6beta1, so no stable release impacted. + +Other bug fixes in universes, type class shelving,... + +Details of changes in 8.6.1 +~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +- Fix #5380: Default colors for CoqIDE are actually applied. +- Fix plugin warnings +- Document named evars (including Show ident) +- Fix Bug #5574, document function scope +- Adding a test case as requested in bug 5205. +- Fix Bug #5568, no dup notation warnings on repeated module imports +- Fix documentation of Typeclasses eauto := +- Refactor documentation of records. +- Protecting from warnings while compiling 8.6 +- Fixing an inconsistency between configure and configure.ml +- Add test-suite checks for coqchk with constraints +- Fix bug #5019 (looping zify on dependent types) +- Fix bug 5550: "typeclasses eauto with" does not work with section variables. +- Bug 5546, qualify datatype constructors when needed in Show Match +- Bug #5535, test for Show with -emacs +- Fix bug #5486, don't reverse ids in tuples +- Fixing #5522 (anomaly with free vars of pat) +- Fix bug #5526, don't check for nonlinearity in notation if printing only +- Fix bug #5255 +- Fix bug #3659: -time should understand multibyte encodings. +- FIx bug #5300: Anomaly: Uncaught exception Not_found" in "Print Assumptions". +- Fix outdated description in RefMan. +- Repairing `Set Rewriting Schemes` +- Fixing #5487 (v8.5 regression on ltac-matching expressions with evars). +- Fix description of command-line arguments for Add (Rec) LoadPath +- Fix bug #5377: @? patterns broken. +- add XML protocol doc +- Fix anomaly when doing [all:Check _.] during a proof. +- Correction of bug #4306 +- Fix #5435: [Eval native_compute in] raises anomaly. +- Instances should obey universe binders even when defined by tactics. +- Intern names bound in match patterns +- funind: Ignore missing info for current function +- Do not typecheck twice the type of opaque constants. +- show unused intro pattern warning +- [future] Be eager when "chaining" already resolved future values. +- Opaque side effects +- Fix #5132: coq_makefile generates incorrect install goal +- Run non-tactic comands without resilient_command +- Univs: fix bug #5365, generation of u+k <= v constraints +- make ``emit`` tail recursive +- Don't require printing-only notation to be productive +- Fix the way setoid_rewrite handles bindings. +- Fix for bug 5244 - set printing width ignored when given enough space +- Fix bug 4969, autoapply was not tagging shelved subgoals correctly + +Version 8.5 +----------- + +Summary of changes +~~~~~~~~~~~~~~~~~~ + +Coq version 8.5 contains the result of five specific long-term projects: + +- A new asynchronous evaluation and compilation mode by Enrico Tassi + with help from Bruno Barras and Carst Tankink. + +- Full integration of the new proof engine by Arnaud Spiwack helped by + Pierre-Marie Pédrot, + +- Addition of conversion and reduction based on native compilation by + Maxime Dénès and Benjamin Grégoire. + +- Full universe polymorphism for definitions and inductive types by + Matthieu Sozeau. + +- An implementation of primitive projections with + :math:`\eta`\-conversion bringing significant performance improvements + when using records by Matthieu Sozeau. + +The full integration of the proof engine, by Arnaud Spiwack and +Pierre-Marie Pédrot, brings to primitive tactics and the user level Ltac +language dependent subgoals, deep backtracking and multiple goal +handling, along with miscellaneous features and an improved potential +for future modifications. Dependent subgoals allow statements in a goal +to mention the proof of another. Proofs of unsolved subgoals appear as +existential variables. Primitive backtracking makes it possible to write +a tactic with several possible outcomes which are tried successively +when subsequent tactics fail. Primitives are also available to control +the backtracking behavior of tactics. Multiple goal handling paves the +way for smarter automation tactics. It is currently used for simple goal +manipulation such as goal reordering. + +The way |Coq| processes a document in batch and interactive mode has been +redesigned by Enrico Tassi with help from Bruno Barras. Opaque proofs, +the text between Proof and Qed, can be processed asynchronously, +decoupling the checking of definitions and statements from the checking +of proofs. It improves the responsiveness of interactive development, +since proofs can be processed in the background. Similarly, compilation +of a file can be split into two phases: the first one checking only +definitions and statements and the second one checking proofs. A file +resulting from the first phase – with the .vio extension – can be +already Required. All .vio files can be turned into complete .vo files +in parallel. The same infrastructure also allows terminating tactics to +be run in parallel on a set of goals via the ``par:`` goal selector. + +|CoqIDE| was modified to cope with asynchronous checking of the document. +Its source code was also made separate from that of |Coq|, so that |CoqIDE| +no longer has a special status among user interfaces, paving the way for +decoupling its release cycle from that of |Coq| in the future. + +Carst Tankink developed a |Coq| back-end for user interfaces built on +Makarius Wenzel’s Prover IDE framework (PIDE), like PIDE/jEdit (with +help from Makarius Wenzel) or PIDE/Coqoon (with help from Alexander +Faithfull and Jesper Bengtson). The development of such features was +funded by the Paral-ITP French ANR project. + +The full universe polymorphism extension was designed by Matthieu +Sozeau. It conservatively extends the universes system and core calculus +with definitions and inductive declarations parameterized by universes +and constraints. It is based on a modification of the kernel +architecture to handle constraint checking only, leaving the generation +of constraints to the refinement/type inference engine. Accordingly, +tactics are now fully universe aware, resulting in more localized error +messages in case of inconsistencies and allowing higher-level algorithms +like unification to be entirely type safe. The internal representation +of universes has been modified but this is invisible to the user. + +The underlying logic has been extended with :math:`\eta`\-conversion for +records defined with primitive projections by Matthieu Sozeau. This +additional form of :math:`\eta`\-conversion is justified using the same +principle than the previously added :math:`\eta`\-conversion for function +types, based on formulations of the Calculus of Inductive Constructions +with typed equality. Primitive projections, which do not carry the +parameters of the record and are rigid names (not defined as a +pattern matching construct), make working with nested records more +manageable in terms of time and space consumption. This extension and +universe polymorphism were carried out partly while Matthieu Sozeau was +working at the IAS in Princeton. + +The guard condition has been made compliant with extensional equality +principles such as propositional extensionality and univalence, thanks +to Maxime Dénès and Bruno Barras. To ensure compatibility with the +univalence axiom, a new flag ``-indices-matter`` has been implemented, +taking into account the universe levels of indices when computing the +levels of inductive types. This supports using |Coq| as a tool to explore +the relations between homotopy theory and type theory. + +Maxime Dénès and Benjamin Grégoire developed an implementation of +conversion test and normal form computation using the OCaml native +compiler. It complements the virtual machine conversion offering much +faster computation for expensive functions. + +Coq 8.5 also comes with a bunch of many various smaller-scale changes +and improvements regarding the different components of the system. We +shall only list a few of them. + +Pierre Boutillier developed an improved tactic for simplification of +expressions called :tacn:`cbn`. + +Maxime Dénès maintained the bytecode-based reduction machine. Pierre +Letouzey maintained the extraction mechanism. + +Pierre-Marie Pédrot has extended the syntax of terms to, experimentally, +allow holes in terms to be solved by a locally specified tactic. + +Existential variables are referred to by identifiers rather than mere +numbers, thanks to Hugo Herbelin who also improved the tactic language +here and there. + +Error messages for universe inconsistencies have been improved by +Matthieu Sozeau. Error messages for unification and type inference +failures have been improved by Hugo Herbelin, Pierre-Marie Pédrot and +Arnaud Spiwack. + +Pierre Courtieu contributed new features for using |Coq| through Proof +General and for better interactive experience (bullets, Search, etc). + +The efficiency of the whole system has been significantly improved +thanks to contributions from Pierre-Marie Pédrot. + +A distribution channel for |Coq| packages using the OPAM tool has been +initiated by Thomas Braibant and developed by Guillaume Claret, with +contributions by Enrico Tassi and feedback from Hugo Herbelin. + +Packaging tools were provided by Pierre Letouzey and Enrico Tassi +(Windows), Pierre Boutillier, Matthieu Sozeau and Maxime Dénès (MacOS +X). Maxime Dénès improved significantly the testing and benchmarking +support. + +Many power users helped to improve the design of the new features via +the bug tracker, the coq development mailing list or the Coq-Club +mailing list. Special thanks are going to the users who contributed +patches and intensive brain-storming, starting with Jason Gross, +Jonathan Leivent, Greg Malecha, Clément Pit-Claudel, Marc Lasson, Lionel +Rieg. It would however be impossible to mention with precision all names +of people who to some extent influenced the development. + +Version 8.5 is one of the most important releases of |Coq|. Its development +spanned over about 3 years and a half with about one year of +beta-testing. General maintenance during part or whole of this period +has been done by Pierre Boutillier, Pierre Courtieu, Maxime Dénès, Hugo +Herbelin, Pierre Letouzey, Guillaume Melquiond, Pierre-Marie Pédrot, +Matthieu Sozeau, Arnaud Spiwack, Enrico Tassi as well as Bruno Barras, +Yves Bertot, Frédéric Besson, Xavier Clerc, Pierre Corbineau, +Jean-Christophe Filliâtre, Julien Forest, Sébastien Hinderer, Assia +Mahboubi, Jean-Marc Notin, Yann Régis-Gianas, François Ripault, Carst +Tankink. Maxime Dénès coordinated the release process. + +| Paris, January 2015, revised December 2015, +| Hugo Herbelin, Matthieu Sozeau and the |Coq| development team +| + +Potential sources of incompatibilities +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +List of typical changes to be done to adapt files from Coq 8.4 +to Coq 8.5 when not using compatibility option ``-compat 8.4``. + +- Symptom: "The reference omega was not found in the current environment". + + Cause: "Require Omega" does not import the tactic "omega" any more + + Possible solutions: + + + use "Require Import OmegaTactic" (not compatible with 8.4) + + use "Require Import Omega" (compatible with 8.4) + + add definition "Ltac omega := Coq.omega.Omega.omega." + +- Symptom: "intuition" cannot solve a goal (not working anymore on non standard connective) + + Cause: "intuition" had an accidental non uniform behavior fixed on non standard connectives + + Possible solutions: + + + use "dintuition" instead; it is stronger than "intuition" and works + uniformly on non standard connectives, such as n-ary conjunctions or disjunctions + (not compatible with 8.4) + + do the script differently + +- Symptom: The constructor foo (in type bar) expects n arguments. + + Cause: parameters must now be given in patterns + + Possible solutions: + + + use option "Set Asymmetric Patterns" (compatible with 8.4) + + add "_" for the parameters (not compatible with 8.4) + + turn the parameters into implicit arguments (compatible with 8.4) + +- Symptom: "NPeano.Nat.foo" not existing anymore\ + + Possible solutions: + + + use "Nat.foo" instead + + Symptom: typing problems with proj1_sig or similar + + Cause: coercion from sig to sigT and similar coercions have been + removed so as to make the initial state easier to understand for + beginners + + Solution: change proj1_sig into projT1 and similarly (compatible with 8.4) + +Other detailed changes + +- options for *coq* compilation (see below for ocaml). + + + [-I foo] is now deprecated and will not add directory foo to the + coq load path (only for ocaml, see below). Just replace [-I foo] by + [-Q foo ""] in your project file and re-generate makefile. Or + perform the same operation directly in your makefile if you edit it + by hand. + + + Option -R Foo bar is the same in v8.5 than in v8.4 concerning coq + load path. + + + Option [-I foo -as bar] is unchanged but discouraged unless you + compile ocaml code. Use -Q foo bar instead. + + for more details: see section "Customization at launch + time" of the reference manual. + +- Command line options for ocaml Compilation of ocaml code (plugins) + + + [-I foo] is *not* deprecated to add foo to the ocaml load path. + + + [-I foo -as bar] adds foo to the ocaml load path *and* adds foo to + the coq load path with logical name bar (shortcut for -I foo -Q foo + bar). + + for more details: section "Customization at launch + time" of the reference manual. + +- Universe Polymorphism. + +- Refinement, unification and tactics are now aware of universes, + resulting in more localized errors. Universe inconsistencies + should no more get raised at Qed time but during the proof. + Unification *always* produces well-typed substitutions, hence + some rare cases of unifications that succeeded while producing + ill-typed terms before will now fail. + +- The [change p with c] tactic semantics changed, now typechecking + [c] at each matching occurrence [t] of the pattern [p], and + converting [t] with [c]. + +- Template polymorphic inductive types: the partial application + of a template polymorphic type (e.g. list) is not polymorphic. + An explicit parameter application (e.g [fun A => list A]) or + [apply (list _)] will result in a polymorphic instance. + +- The type inference algorithm now takes opacity of constants into + account. This may have effects on tactics using type inference + (e.g. induction). Extra "Transparent" might have to be added to + revert opacity of constants. + +Type classes. + +- When writing an ``Instance foo : Class A := {| proj := t |}`` (note the + vertical bars), support for typechecking the projections using the + type information and switching to proof mode is no longer available. + Use ``{ }`` (without the vertical bars) instead. + +Tactic abstract. + +- Auxiliary lemmas generated by the abstract tactic are removed from + the global environment and inlined in the proof term when a proof + is ended with Qed. The behavior of 8.4 can be obtained by ending + proofs with "Qed exporting" or "Qed exporting ident, .., ident". + +Details of changes in 8.5beta1 +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Logic + +- Primitive projections for records allow for a compact representation + of projections, without parameters and avoid the behavior of defined + projections that can unfold to a case expression. To turn the use of + native projections on, use [Set Primitive Projections]. Record, + Class and Structure types defined while this option is set will be + defined with primitive projections instead of the usual encoding as + a case expression. For compatibility, when p is a primitive + projection, @p can be used to refer to the projection with explicit + parameters, i.e. [@p] is definitionally equal to [λ params r. r.(p)]. + Records with primitive projections have eta-conversion, the + canonical form being [mkR pars (p1 t) ... (pn t)]. +- New universe polymorphism (see reference manual) +- New option -type-in-type to collapse the universe hierarchy (this makes the + logic inconsistent). +- The guard condition for fixpoints is now a bit stricter. Propagation + of subterm value through pattern matching is restricted according to + the return predicate. Restores compatibility of Coq's logic with the + propositional extensionality axiom. May create incompatibilities in + recursive programs heavily using dependent types. +- Trivial inductive types are no longer defined in Type but in Prop, which + leads to a non-dependent induction principle being generated in place of + the dependent one. To recover the old behavior, explicitly define your + inductive types in Set. + +Vernacular commands + +- A command "Variant" allows to define non-recursive variant types. +- The command "Record foo ..." does not generate induction principles + (foo_rect, foo_rec, foo_ind) anymore by default (feature wish + #2693). The command "Variant foo ..." does not either. A flag + "Set/Unset Nonrecursive Elimination Schemes" allows changing this. + The tactic "induction" on a "Record" or a "Variant" is now actually + doing "destruct". +- The "Open Scope" command can now be given also a delimiter (e.g. Z). +- The "Definition" command now allows the "Local" modifier, allowing + for non-importable definitions. The same goes for "Axiom" and "Parameter". +- Section-specific commands such as "Let" (resp. "Variable", "Hypothesis") used + out of a section now behave like the corresponding "Local" command, i.e. + "Local Definition" (resp. "Local Parameter", "Local Axiom"). (potential source + of rare incompatibilities). +- The "Let" command can now define local (co)fixpoints. +- Command "Search" has been renamed into "SearchHead". The command + name "Search" now behaves like former "SearchAbout". The latter name + is deprecated. +- "Search", "About", "SearchHead", "SearchRewrite" and "SearchPattern" + now search for hypothesis (of the current goal by default) first. + They now also support the goal selector prefix to specify another + goal to search: e.g. "n:Search id". This is also true for + SearchAbout although it is deprecated. +- The coq/user-contrib directory and the XDG directories are no longer + recursively added to the load path, so files from installed libraries + now need to be fully qualified for the "Require" command to find them. + The tools/update-require script can be used to convert a development. +- A new Print Strategies command allows visualizing the opacity status + of the whole engine. +- The "Locate" command now searches through all sorts of qualified namespaces of + Coq: terms, modules, tactics, etc. The old behavior of the command can be + retrieved using the "Locate Term" command. +- New "Derive" command to help writing program by derivation. +- New "Refine Instance Mode" option that allows to deactivate the generation of + obligations in incomplete typeclass instances, raising an error instead. +- "Collection" command to name sets of section hypotheses. Named collections + can be used in the syntax of "Proof using" to assert which section variables + are used in a proof. +- The "Optimize Proof" command can be placed in the middle of a proof to + force the compaction of the data structure used to represent the ongoing + proof (evar map). This may result in a lower memory footprint and speed up + the execution of the following tactics. +- "Optimize Heap" command to tell the OCaml runtime to perform a major + garbage collection step and heap compaction. +- ``Instance`` no longer treats the ``{|...|}`` syntax specially; it handles it + in the same way as other commands, e.g. "Definition". Use the ``{...}`` + syntax (no pipe symbols) to recover the old behavior. + +Specification Language + +- Slight changes in unification error messages. +- Added a syntax $(...)$ that allows putting tactics in terms (may + break user notations using "$(", fixable by inserting a space or + rewriting the notation). +- Constructors in pattern-matching patterns now respect the same rules + regarding implicit arguments as in applicative position. The old + behavior can be recovered by the command "Set Asymmetric + Patterns". As a side effect, notations for constructors explicitly + mentioning non-implicit parameters can now be used in patterns. + Considering that the pattern language is already rich enough, binding + local definitions is however now forbidden in patterns (source of + incompatibilities for local definitions that delta-reduce to a constructor). +- Type inference algorithm now granting opacity of constants. This might also + affect behavior of tactics (source of incompatibilities, solvable by + re-declaring transparent constants which were set opaque). +- Existential variables are now referred to by an identifier and the + relevant part of their instance is displayed by default. They can be + reparsed. The naming policy is yet unstable and subject to changes + in future releases. + +Tactics + +- New tactic engine allowing dependent subgoals, fully backtracking + (also known as multiple success) tactics, as well as tactics which + can consider multiple goals together. In the new tactic engine, + instantiation information of existential variables is always + propagated to tactics, removing the need to manually use the + "instantiate" tactics to mark propagation points. + + * New tactical (a+b) inserts a backtracking point. When (a+b);c fails + during the execution of c, it can backtrack and try b instead of a. + * New tactical (once a) removes all the backtracking points from a + (i.e. it selects the first success of a). + * Tactic "constructor" is now fully backtracking. In case of + incompatibilities (e.g. combinatoric explosion), the former + behavior of "constructor" can be retrieved by using instead + "[> once constructor ..]". Thanks to backtracking, undocumented + "constructor <tac>" syntax is now equivalent to + "[> once (constructor; tac) ..]". + * New "multimatch" variant of "match" tactic which backtracks to + new branches in case of a later failure. The "match" tactic is + equivalent to "once multimatch". + * New selector "all:" such that "all:tac" applies tactic "tac" to + all the focused goals, instead of just the first one as is the + default. + * A corresponding new option Set Default Goal Selector "all" makes + the tactics in scripts be applied to all the focused goal by default + * New selector "par:" such that "par:tac" applies the (terminating) + tactic "tac" to all the focused goal in parallel. The number of worker + can be selected with -async-proofs-tac-j and also limited using the + coqworkmgr utility. + * New tactics "revgoals", "cycle" and "swap" to reorder goals. + * The semantics of recursive tactics (introduced with "Ltac t := ..." + or "let rec t := ... in ...") changed slightly as t is now + applied to every goal, not each goal independently. In particular + it may be applied when no goals are left. This may cause tactics + such as "let rec t := constructor;t" to loop indefinitely. The + simple fix is to rewrite the recursive calls as follows: + "let rec t := constructor;[t..]" which recovers the earlier behavior + (source of rare incompatibilities). + * New tactic language feature "numgoals" to count number of goals. It is + accompanied by a "guard" tactic which fails if a Boolean test over + integers does not pass. + * New tactical "[> ... ]" to apply tactics to individual goals. + * New tactic "gfail" which works like "fail" except it will also + fail if every goal has been solved. + * The refine tactic is changed not to use an ad hoc typing algorithm + to generate subgoals. It also uses the dependent subgoal feature + to generate goals to materialize every existential variable which + is introduced by the refinement (source of incompatibilities). + * A tactic shelve is introduced to manage the subgoals which may be + solved by unification: shelve removes every goal it is applied to + from focus. These goals can later be called back into focus by the + Unshelve command. + * A variant shelve_unifiable only removes those goals which appear + as existential variables in other goals. To emulate the old + refine, use "refine c;shelve_unifiable". This can still cause + incompatibilities in rare occasions. + * New "give_up" tactic to skip over a goal. A proof containing + given up goals cannot be closed with "Qed", but only with "Admitted". + +- The implementation of the admit tactic has changed: no axiom is + generated for the admitted sub proof. "admit" is now an alias for + "give_up". Code relying on this specific behavior of "admit" + can be made to work by: + + * Adding an "Axiom" for each admitted subproof. + * Adding a single "Axiom proof_admitted : False." and the Ltac definition + "Ltac admit := case proof_admitted.". + +- Matching using "lazymatch" was fundamentally modified. It now behaves + like "match" (immediate execution of the matching branch) but without + the backtracking mechanism in case of failure. + +- New "tryif t then u else v" tactical which executes "u" in case of success + of "t" and "v" in case of failure. + +- New conversion tactic "native_compute": evaluates the goal (or an hypothesis) + with a call-by-value strategy, using the OCaml native compiler. Useful on + very intensive computations. + +- New "cbn" tactic, a well-behaved simpl. + +- Repeated identical calls to omega should now produce identical proof terms. + +- Tactics btauto, a reflexive Boolean tautology solver. + +- Tactic "tauto" was exceptionally able to destruct other connectives + than the binary connectives "and", "or", "prod", "sum", "iff". This + non-uniform behavior has been fixed (bug #2680) and tauto is + slightly weaker (possible source of incompatibilities). On the + opposite side, new tactic "dtauto" is able to destruct any + record-like inductive types, superseding the old version of "tauto". + +- Similarly, "intuition" has been made more uniform and, where it now + fails, "dintuition" can be used (possible source of incompatibilities). + +- New option "Unset Intuition Negation Unfolding" for deactivating automatic + unfolding of "not" in intuition. + +- Tactic notations can now be defined locally to a module (use "Local" prefix). + +- Tactic "red" now reduces head beta-iota redexes (potential source of + rare incompatibilities). + +- Tactic "hnf" now reduces inner beta-iota redexes + (potential source of rare incompatibilities). + +- Tactic "intro H" now reduces beta-iota redexes if these hide a product + (potential source of rare incompatibilities). + +- In Ltac matching on patterns of the form "_ pat1 ... patn" now + behaves like if matching on "?X pat1 ... patn", i.e. accepting "_" + to be instantiated by an applicative term (experimental at this + stage, potential source of incompatibilities). + +- In Ltac matching on goal, types of hypotheses are now interpreted in + the %type scope (possible source of incompatibilities). + +- "change ... in ..." and "simpl ... in ..." now properly consider nested + occurrences (possible source of incompatibilities since this alters + the numbering of occurrences), but do not support nested occurrences. + +- Tactics simpl, vm_compute and native_compute can be given a notation string + to a constant as argument. + +- When given a reference as argument, simpl, vm_compute and + native_compute now strictly interpret it as the head of a pattern + starting with this reference. + +- The "change p with c" tactic semantics changed, now type-checking + "c" at each matching occurrence "t" of the pattern "p", and + converting "t" with "c". + +- Now "appcontext" and "context" behave the same. The old buggy behavior of + "context" can be retrieved at parse time by setting the + "Tactic Compat Context" flag (possible source of incompatibilities). + +- New introduction pattern p/c which applies lemma c on the fly on the + hypothesis under consideration before continuing with introduction pattern p. + +- New introduction pattern [= x1 .. xn] applies "injection as [x1 .. xn]" + on the fly if injection is applicable to the hypothesis under consideration + (idea borrowed from Georges Gonthier). Introduction pattern [=] applies + "discriminate" if a discriminable equality. + +- New introduction patterns * and ** to respectively introduce all forthcoming + dependent variables and all variables/hypotheses dependent or not. + +- Tactic "injection c as ipats" now clears c if c refers to an + hypothesis and moves the resulting equations in the hypotheses + independently of the number of ipats, which has itself to be less + than the number of new hypotheses (possible source of incompatibilities; + former behavior obtainable by "Unset Injection L2R Pattern Order"). + +- Tactic "injection" now automatically simplifies subgoals + "existT n p = existT n p'" into "p = p'" when "n" is in an inductive type for + which a decidable equality scheme has been generated with "Scheme Equality" + (possible source of incompatibilities). + +- New tactic "rewrite_strat" for generalized rewriting with user-defined + strategies, subsuming autorewrite. + +- Injection can now also deduce equality of arguments of sort Prop, by using + the option "Set Injection On Proofs" (disabled by default). Also improved the + error messages. + +- Tactic "subst id" now supports id occurring in dependent local definitions. + +- Bugs fixed about intro-pattern "*" might lead to some rare incompatibilities. + +- New tactical "time" to display time spent executing its argument. + +- Tactics referring or using a constant dependent in a section variable which + has been cleared or renamed in the current goal context now fail + (possible source of incompatibilities solvable by avoiding clearing + the relevant hypotheses). + +- New construct "uconstr:c" and "type_term c" to build untyped terms. + +- Binders in terms defined in Ltac (either "constr" or "uconstr") can + now take their names from identifiers defined in Ltac. As a + consequence, a name cannot be used in a binder "constr:(fun x => + ...)" if an Ltac variable of that name already exists and does not + contain an identifier. Source of occasional incompatibilities. + +- The "refine" tactic now accepts untyped terms built with "uconstr" + so that terms with holes can be constructed piecewise in Ltac. + +- New bullets --, ++, **, ---, +++, ***, ... made available. + +- More informative messages when wrong bullet is used. + +- Bullet suggestion when a subgoal is solved. + +- New tactic "enough", symmetric to "assert", but with subgoals + swapped, as a more friendly replacement of "cut". + +- In destruct/induction, experimental modifier "!" prefixing the + hypothesis name to tell not erasing the hypothesis. + +- Bug fixes in "inversion as" may occasionally lead to incompatibilities. + +- Behavior of introduction patterns -> and <- made more uniform + (hypothesis is cleared, rewrite in hypotheses and conclusion and + erasing the variable when rewriting a variable). + +- New experimental option "Set Standard Proposition Elimination Names" + so that case analysis or induction on schemes in Type containing + propositions now produces "H"-based names. + +- Tactics from plugins are now active only when the corresponding module + is imported (source of incompatibilities, solvable by adding an "Import"; + in the particular case of Omega, use "Require Import OmegaTactic"). + +- Semantics of destruct/induction has been made more regular in some + edge cases, possibly leading to incompatibilities: + + + new goals are now opened when the term does not match a subterm of + the goal and has unresolved holes, while in 8.4 these holes were + turned into existential variables + + when no "at" option is given, the historical semantics which + selects all subterms syntactically identical to the first subterm + matching the given pattern is used + + non-dependent destruct/induction on an hypothesis with premises in + an inductive type with indices is fixed + + residual local definitions are now correctly removed. + +- The rename tactic may now replace variables in parallel. + +- A new "Info" command replaces the "info" tactical discontinued in + v8.4. It still gives informative results in many cases. + +- The "info_auto" tactic is known to be broken and does not print a + trace anymore. Use "Info 1 auto" instead. The same goes for + "info_trivial". On the other hand "info_eauto" still works fine, + while "Info 1 eauto" prints a trivial trace. + +- When using a lemma of the prototypical form "forall A, {a:A & P a}", + "apply" and "apply in" do not instantiate anymore "A" with the + current goal and use "a" as the proof, as they were sometimes doing, + now considering that it is a too powerful decision. + +Program + +- "Solve Obligations using" changed to "Solve Obligations with", + consistent with "Proof with". +- Program Lemma, Definition now respect automatic introduction. +- Program Lemma, Definition, etc.. now interpret "->" like Lemma and + Definition as a non-dependent arrow (potential source of + incompatibility). +- Add/document "Set Hide Obligations" (to hide obligations in the final + term inside an implicit argument) and "Set Shrink Obligations" (to + minimize dependencies of obligations defined by tactics). + +Notations + +- The syntax "x -> y" is now declared at level 99. In particular, it has + now a lower priority than "<->": "A -> B <-> C" is now "A -> (B <-> C)" + (possible source of incompatibilities) +- Notations accept term-providing tactics using the $(...)$ syntax. +- "Bind Scope" can no longer bind "Funclass" and "Sortclass". +- A notation can be given a (compat "8.x") annotation, making it behave + like a "only parsing" notation, but the annotation may lead to eventually + issue warnings or errors in further versions when this notation is used. +- More systematic insertion of spaces as a default for printing + notations ("format" still available to override the default). +- In notations, a level modifier referring to a non-existent variable is + now considered an error rather than silently ignored. + +Tools + +- Option -I now only adds directories to the ml path. +- Option -Q behaves as -R, except that the logical path of any loaded file has + to be fully qualified. +- Option -R no longer adds recursively to the ml path; only the root + directory is added. (Behavior with respect to the load path is + unchanged.) +- Option -nois prevents coq/theories and coq/plugins to be recursively + added to the load path. (Same behavior as with coq/user-contrib.) +- coqdep accepts a -dumpgraph option generating a dot file. +- Makefiles generated through coq_makefile have three new targets "quick" + "checkproofs" and "vio2vo", allowing respectively to asynchronously compile + the files without playing the proof scripts, asynchronously checking + that the quickly generated proofs are correct and generating the object + files from the quickly generated proofs. +- The XML plugin was discontinued and removed from the source. +- A new utility called coqworkmgr can be used to limit the number of + concurrent workers started by independent processes, like make and CoqIDE. + This is of interest for users of the par: goal selector. + +Interfaces + +- CoqIDE supports asynchronous edition of the document, ongoing tasks and + errors are reported in the bottom right window. The number of workers + taking care of processing proofs can be selected with -async-proofs-j. +- CoqIDE highlights in yellow "unsafe" commands such as axiom + declarations, and tactics like "give_up". +- CoqIDE supports Proof General like key bindings; + to activate the PG mode go to Edit -> Preferences -> Editor. + For the documentation see Help -> Help for PG mode. +- CoqIDE automatically retracts the locked area when one edits the + locked text. +- CoqIDE search and replace got regular expressions power. See the + documentation of OCaml's Str module for the supported syntax. +- Many CoqIDE windows, including the query one, are now detachable to + improve usability on multi screen work stations. +- Coqtop/coqc outputs highlighted syntax. Colors can be configured thanks + to the COQ_COLORS environment variable, and their current state can + be displayed with the -list-tags command line option. +- Third party user interfaces can install their main loop in $COQLIB/toploop + and call coqtop with the -toploop flag to select it. + +Internal Infrastructure + +- Many reorganizations in the ocaml source files. For instance, + many internal a.s.t. of Coq are now placed in mli files in + a new directory intf/, for instance constrexpr.mli or glob_term.mli. + More details in dev/doc/changes. + +- The file states/initial.coq does not exist anymore. Instead, coqtop + initially does a "Require" of Prelude.vo (or nothing when given + the options -noinit or -nois). + +- The format of vo files has slightly changed: cf final comments in + checker/cic.mli. + +- The build system does not produce anymore programs named coqtop.opt + and a symbolic link to coqtop. Instead, coqtop is now directly + an executable compiled with the best OCaml compiler available. + The bytecode program coqtop.byte is still produced. Same for other + utilities. + +- Some options of the ./configure script slightly changed: + + * The -coqrunbyteflags and its blank-separated argument is replaced + by option -vmbyteflags which expects a comma-separated argument. + * The -coqtoolsbyteflags option is discontinued, see -no-custom instead. + +Miscellaneous + +- ML plugins now require a "DECLARE PLUGIN \"foo\"" statement. The "foo" name + must be exactly the name of the ML module that will be loaded through a + "Declare ML \"foo\"" command. + +Details of changes in 8.5beta2 +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Logic + +- The VM now supports inductive types with up to 8388851 non-constant + constructors and up to 8388607 constant ones. + +Specification language + +- Syntax "$(tactic)$" changed to "ltac: tactic". + +Tactics + +- A script using the admit tactic can no longer be concluded by either + Qed or Defined. In the first case, Admitted can be used instead. In + the second case, a subproof should be used. +- The easy tactic and the now tactical now have a more predictable + behavior, but they might now discharge some previously unsolved goals. + +Extraction + +- Definitions extracted to Haskell GHC should no longer randomly + segfault when some Coq types cannot be represented by Haskell types. +- Definitions can now be extracted to Json for post-processing. + +Tools + +- Option -I -as has been removed, and option -R -as has been + deprecated. In both cases, option -R can be used instead. +- coq_makefile now generates double-colon rules for rules such as clean. + +API + +- The interface of [change] has changed to take a [change_arg], which + can be built from a [constr] using [make_change_arg]. + +Details of changes in 8.5beta3 +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Vernacular commands + +- New command "Redirect" to redirect the output of a command to a file. +- New command "Undelimit Scope" to remove the delimiter of a scope. +- New option "Strict Universe Declaration", set by default. It enforces the + declaration of all polymorphic universes appearing in a definition when + introducing it. +- New command "Show id" to show goal named id. +- Option "Virtual Machine" removed. + +Tactics + +- New flag "Regular Subst Tactic" which fixes "subst" in situations where + it failed to substitute all substitutable equations or failed to simplify + cycles, or accidentally unfolded local definitions (flag is off by default). +- New flag "Loose Hint Behavior" to handle hints loaded but not imported in a + special way. It accepts three distinct flags: + * "Lax", which is the default one, sets the old behavior, i.e. a non-imported + hint behaves the same as an imported one. + * "Warn" outputs a warning when a non-imported hint is used. Note that this is + an over-approximation, because a hint may be triggered by an eauto run that + will eventually fail and backtrack. + * "Strict" changes the behavior of an unloaded hint to the one of the fail + tactic, allowing to emulate the hopefully future import-scoped hint mechanism. +- New compatibility flag "Universal Lemma Under Conjunction" which + let tactics working under conjunctions apply sublemmas of the form + "forall A, ... -> A". +- New compatibility flag "Bracketing Last Introduction Pattern" which can be + set so that the last disjunctive-conjunctive introduction pattern given to + "intros" automatically complete the introduction of its subcomponents, as the + the disjunctive-conjunctive introduction patterns in non-terminal position + already do. +- New flag "Shrink Abstract" that minimalizes proofs generated by the abstract + tactical w.r.t. variables appearing in the body of the proof. + +Program + +- The "Shrink Obligations" flag now applies to all obligations, not only those + solved by the automatic tactic. +- Importing Program no longer overrides the "exists" tactic (potential source + of incompatibilities). +- Hints costs are now correctly taken into account (potential source of + incompatibilities). +- Documented the Hint Cut command that allows control of the + proof-search during typeclass resolution (see reference manual). + +API + +- Some functions from pretyping/typing.ml and their derivatives were potential + source of evarmap leaks, as they dropped their resulting evarmap. The + situation was clarified by renaming them according to a ``unsafe_*`` scheme. Their + sound variant is likewise renamed to their old name. The following renamings + were made. + + * ``Typing.type_of`` -> ``unsafe_type_of`` + * ``Typing.e_type_of`` -> ``type_of`` + * A new ``e_type_of`` function that matches the ``e_`` prefix policy + * ``Tacmach.pf_type_of`` -> ``pf_unsafe_type_of`` + * A new safe ``pf_type_of`` function. + + All uses of ``unsafe_*`` functions should be eventually eliminated. + +Tools + +- Added an option -w to control the output of coqtop warnings. +- Configure now takes an optional -native-compiler (yes|no) flag replacing + -no-native-compiler. The new flag is set to no by default under Windows. +- Flag -no-native-compiler was removed and became the default for coqc. If + precompilation of files for native conversion test is desired, use + -native-compiler. +- The -compile command-line option now takes the full path of the considered + file, including the ".v" extension, and outputs a warning if such an extension + is lacking. +- The -require and -load-vernac-object command-line options now take a logical + path of a given library rather than a physical path, thus they behave like + Require [Import] path. +- The -vm command-line option has been removed. + +Standard Library + + - There is now a Coq.Compat.Coq84 library, which sets the various compatibility + options and does a few redefinitions to make Coq behave more like Coq v8.4. + The standard way of putting Coq in v8.4 compatibility mode is to pass the command + line flags "-require Coq.Compat.Coq84 -compat 8.4". + +Details of changes in 8.5 +~~~~~~~~~~~~~~~~~~~~~~~~~ + +Tools + +- Flag "-compat 8.4" now loads Coq.Compat.Coq84. The standard way of + putting Coq in v8.4 compatibility mode is to pass the command line flag + "-compat 8.4". It can be followed by "-require Coq.Compat.AdmitAxiom" + if the 8.4 behavior of admit is needed, in which case it uses an axiom. + +Specification language + +- Syntax "$(tactic)$" changed to "ltac:(tactic)". + +Tactics + +- Syntax "destruct !hyp" changed to "destruct (hyp)", and similarly + for induction (rare source of incompatibilities easily solvable by + removing parentheses around "hyp" when not for the purpose of keeping + the hypothesis). +- Syntax "p/c" for on-the-fly application of a lemma c before + introducing along pattern p changed to p%c1..%cn. The feature and + syntax are in experimental stage. +- "Proof using" does not clear unused section variables. +- Tactic "refine" has been changed back to the 8.4 behavior of shelving subgoals + that occur in other subgoals. The "refine" tactic of 8.5beta3 has been + renamed "simple refine"; it does not shelve any subgoal. +- New tactical "unshelve tac" which grab existential variables put on + the tactic shelve by the execution of "tac". + +Details of changes in 8.5pl1 +~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Critical bugfix + +- The subterm relation for the guard condition was incorrectly defined on + primitive projections (#4588) + +Plugin development tools + +- add a .merlin target to the makefile + +Various performance improvements (time, space used by .vo files) + +Other bugfixes + +- Fix order of arguments to Big.compare_case in ExtrOcamlZBigInt.v +- Added compatibility coercions from Specif.v which were present in Coq 8.4. +- Fixing a source of inefficiency and an artificial dependency in the printer in the congruence tactic. +- Allow to unset the refinement mode of Instance in ML +- Fixing an incorrect use of prod_appvect on a term which was not a product in setoid_rewrite. +- Add -compat 8.4 econstructor tactics, and tests +- Add compatibility Nonrecursive Elimination Schemes +- Fixing the "No applicable tactic" non informative error message regression on apply. +- Univs: fix get_current_context (bug #4603, part I) +- Fix a bug in Program coercion code +- Fix handling of arity of definitional classes. +- #4630: Some tactics are 20x slower in 8.5 than 8.4. +- #4627: records with no declared arity can be template polymorphic. +- #4623: set tactic too weak with universes (regression) +- Fix incorrect behavior of CS resolution +- #4591: Uncaught exception in directory browsing. +- CoqIDE is more resilient to initialization errors. +- #4614: "Fully check the document" is uninterruptable. +- Try eta-expansion of records only on non-recursive ones +- Fix bug when a sort is ascribed to a Record +- Primitive projections: protect kernel from erroneous definitions. +- Fixed bug #4533 with previous Keyed Unification commit +- Win: kill unreliable hence do not waitpid after kill -9 (Close #4369) +- Fix strategy of Keyed Unification +- #4608: Anomaly "output_value: abstract value (outside heap)". +- #4607: do not read native code files if native compiler was disabled. +- #4105: poor escaping in the protocol between CoqIDE and coqtop. +- #4596: [rewrite] broke in the past few weeks. +- #4533 (partial): respect declared global transparency of projections in unification.ml +- #4544: Backtrack on using full betaiota reduction during keyed unification. +- #4540: CoqIDE bottom progress bar does not update. +- Fix regression from 8.4 in reflexivity +- #4580: [Set Refine Instance Mode] also used for Program Instance. +- #4582: cannot override notation [ x ]. MAY CREATE INCOMPATIBILITIES, see #4683. +- STM: Print/Extraction have to be skipped if -quick +- #4542: CoqIDE: STOP button also stops workers +- STM: classify some variants of Instance as regular `` `Fork `` nodes. +- #4574: Anomaly: Uncaught exception Invalid_argument("splay_arity"). +- Do not give a name to anonymous evars anymore. See bug #4547. +- STM: always stock in vio files the first node (state) of a proof +- STM: not delegate proofs that contain Vernac(Module|Require|Import), #4530 +- Don't fail fatally if PATH is not set. +- #4537: Coq 8.5 is slower in typeclass resolution. +- #4522: Incorrect "Warning..." on windows. +- #4373: coqdep does not know about .vio files. +- #3826: "Incompatible module types" is uninformative. +- #4495: Failed assertion in metasyntax.ml. +- #4511: evar tactic can create non-typed evars. +- #4503: mixing universe polymorphic and monomorphic variables and definitions in sections is unsupported. +- #4519: oops, global shadowed local universe level bindings. +- #4506: Anomaly: File "pretyping/indrec.ml", line 169, characters 14-20: Assertion failed. +- #4548: Coqide crashes when going back one command + +Details of changes in 8.5pl2 +~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Critical bugfix + +- Checksums of .vo files dependencies were not correctly checked. +- Unicode-to-ASCII translation was not injective, leading in a soundness bug in + the native compiler. + +Other bugfixes + +- #4097: more efficient occur-check in presence of primitive projections +- #4398: type_scope used consistently in "match goal". +- #4450: eauto does not work with polymorphic lemmas +- #4677: fix alpha-conversion in notations needing eta-expansion. +- Fully preserve initial order of hypotheses in "Regular Subst Tactic" mode. +- #4644: a regression in unification. +- #4725: Function (Error: Conversion test raised an anomaly) and Program + (Error: Cannot infer this placeholder of type) +- #4747: Problem building Coq 8.5pl1 with OCaml 4.03.0: Fatal warnings +- #4752: CoqIDE crash on files not ended by ".v". +- #4777: printing inefficiency with implicit arguments +- #4818: "Admitted" fails due to undefined universe anomaly after calling + "destruct" +- #4823: remote counter: avoid thread race on sockets +- #4841: -verbose flag changed semantics in 8.5, is much harder to use +- #4851: [nsatz] cannot handle duplicated hypotheses +- #4858: Anomaly: Uncaught exception Failure("hd"). Please report. in variant + of nsatz +- #4880: [nsatz_compute] generates invalid certificates if given redundant + hypotheses +- #4881: synchronizing "Declare Implicit Tactic" with backtrack. +- #4882: anomaly with Declare Implicit Tactic on hole of type with evars +- Fix use of "Declare Implicit Tactic" in refine. + triggered by CoqIDE +- #4069, #4718: congruence fails when universes are involved. + +Universes + +- Disallow silently dropping universe instances applied to variables + (forward compatible) +- Allow explicit universe instances on notations, when they can apply + to the head reference of their expansion. + +Build infrastructure + +- New update on how to find camlp5 binary and library at configure time. + +Details of changes in 8.5pl3 +~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Critical bugfix + +- #4876: Guard checker incompleteness when using primitive projections + +Other bugfixes + +- #4780: Induction with universe polymorphism on was creating ill-typed terms. +- #4673: regression in setoid_rewrite, unfolding let-ins for type unification. +- #4754: Regression in setoid_rewrite, allow postponed unification problems to remain. +- #4769: Anomaly with universe polymorphic schemes defined inside sections. +- #3886: Program: duplicate obligations of mutual fixpoints. +- #4994: Documentation typo. +- #5008: Use the "md5" command on OpenBSD. +- #5007: Do not assume the "TERM" environment variable is always set. +- #4606: Output a break before a list only if there was an empty line. +- #5001: metas not cleaned properly in clenv_refine_in. +- #2336: incorrect glob data for module symbols (bug #2336). +- #4832: Remove extraneous dot in error message. +- Anomaly in printing a unification error message. +- #4947: Options which take string arguments are not backwards compatible. +- #4156: micromega cache files are now hidden files. +- #4871: interrupting par:abstract kills coqtop. +- #5043: [Admitted] lemmas pick up section variables. +- Fix name of internal refine ("simple refine"). +- #5062: probably a typo in Strict Proofs mode. +- #5065: Anomaly: Not a proof by induction. +- Restore native compiler optimizations, they were disabled since 8.5! +- #5077: failure on typing a fixpoint with evars in its type. +- Fix recursive notation bug. +- #5095: non relevant too strict test in let-in abstraction. +- Ensuring that the evar name is preserved by "rename". +- #4887: confusion between using and with in documentation of firstorder. +- Bug in subst with let-ins. +- #4762: eauto weaker than auto. +- Remove if_then_else (was buggy). Use tryif instead. +- #4970: confusion between special "{" and non special "{{" in notations. +- #4529: primitive projections unfolding. +- #4416: Incorrect "Error: Incorrect number of goals". +- #4863: abstract in typeclass hint fails. +- #5123: unshelve can impact typeclass resolution +- Fix a collision about the meta-variable ".." in recursive notations. +- Fix printing of info_auto. +- #3209: Not_found due to an occur-check cycle. +- #5097: status of evars refined by "clear" in ltac: closed wrt evars. +- #5150: Missing dependency of the test-suite subsystems in prerequisite. +- Fix a bug in error printing of unif constraints +- #3941: Do not stop propagation of signals when Coq is busy. +- #4822: Incorrect assertion in cbn. +- #3479 parsing of "{" and "}" when a keyword starts with "{" or "}". +- #5127: Memory corruption with the VM. +- #5102: bullets parsing broken by calls to parse_entry. + +Various documentation improvements + +Version 8.4 +----------- + +Summary of changes +~~~~~~~~~~~~~~~~~~ + +Coq version 8.4 contains the result of three long-term projects: a new +modular library of arithmetic by Pierre Letouzey, a new proof engine by +Arnaud Spiwack and a new communication protocol for |CoqIDE| by Vincent +Gross. + +The new modular library of arithmetic extends, generalizes and unifies +the existing libraries on Peano arithmetic (types nat, N and BigN), +positive arithmetic (type positive), integer arithmetic (Z and BigZ) and +machine word arithmetic (type Int31). It provides with unified notations +(e.g. systematic use of add and mul for denoting the addition and +multiplication operators), systematic and generic development of +operators and properties of these operators for all the types mentioned +above, including gcd, pcm, power, square root, base 2 logarithm, +division, modulo, bitwise operations, logical shifts, comparisons, +iterators, ... + +The most visible feature of the new proof engine is the support for +structured scripts (bullets and proof brackets) but, even if yet not +user-available, the new engine also provides the basis for refining +existential variables using tactics, for applying tactics to several +goals simultaneously, for reordering goals, all features which are +planned for the next release. The new proof engine forced Pierre Letouzey +to reimplement info and Show Script differently. + +Before version 8.4, |CoqIDE| was linked to |Coq| with the graphical +interface living in a separate thread. From version 8.4, |CoqIDE| is a +separate process communicating with |Coq| through a textual channel. This +allows for a more robust interfacing, the ability to interrupt |Coq| +without interrupting the interface, and the ability to manage several +sessions in parallel. Relying on the infrastructure work made by Vincent +Gross, Pierre Letouzey, Pierre Boutillier and Pierre-Marie Pédrot +contributed many various refinements of |CoqIDE|. + +Coq 8.4 also comes with a bunch of various smaller-scale changes +and improvements regarding the different components of the system. + +The underlying logic has been extended with :math:`\eta`-conversion +thanks to Hugo Herbelin, Stéphane Glondu and Benjamin Grégoire. The +addition of :math:`\eta`-conversion is justified by the confidence that +the formulation of the Calculus of Inductive Constructions based on +typed equality (such as the one considered in Lee and Werner to build a +set-theoretic model of CIC :cite:`LeeWerner11`) is +applicable to the concrete implementation of |Coq|. + +The underlying logic benefited also from a refinement of the guard +condition for fixpoints by Pierre Boutillier, the point being that it is +safe to propagate the information about structurally smaller arguments +through :math:`\beta`-redexes that are blocked by the “match” +construction (blocked commutative cuts). + +Relying on the added permissiveness of the guard condition, Hugo +Herbelin could extend the pattern matching compilation algorithm so that +matching over a sequence of terms involving dependencies of a term or of +the indices of the type of a term in the type of other terms is +systematically supported. + +Regarding the high-level specification language, Pierre Boutillier +introduced the ability to give implicit arguments to anonymous +functions, Hugo Herbelin introduced the ability to define notations with +several binders (e.g. ``exists x y z, P``), Matthieu Sozeau made the +typeclass inference mechanism more robust and predictable, Enrico +Tassi introduced a command Arguments that generalizes Implicit Arguments +and Arguments Scope for assigning various properties to arguments of +constants. Various improvements in the type inference algorithm were +provided by Matthieu Sozeau and Hugo Herbelin with contributions from +Enrico Tassi. + +Regarding tactics, Hugo Herbelin introduced support for referring to +expressions occurring in the goal by pattern in tactics such as set or +destruct. Hugo Herbelin also relied on ideas from Chung-Kil Hur’s Heq +plugin to introduce automatic computation of occurrences to generalize +when using destruct and induction on types with indices. Stéphane Glondu +introduced new tactics :tacn:`constr_eq`, :tacn:`is_evar`, and :tacn:`has_evar`, to be used +when writing complex tactics. Enrico Tassi added support to fine-tuning +the behavior of :tacn:`simpl`. Enrico Tassi added the ability to specify over +which variables of a section a lemma has to be exactly generalized. +Pierre Letouzey added a tactic timeout and the interruptibility of +:tacn:`vm_compute`. Bug fixes and miscellaneous improvements of the tactic +language came from Hugo Herbelin, Pierre Letouzey and Matthieu Sozeau. + +Regarding decision tactics, Loïc Pottier maintained nsatz, moving in +particular to a typeclass based reification of goals while Frédéric +Besson maintained Micromega, adding in particular support for division. + +Regarding vernacular commands, Stéphane Glondu provided new commands to +analyze the structure of type universes. + +Regarding libraries, a new library about lists of a given length (called +vectors) has been provided by Pierre Boutillier. A new instance of +finite sets based on Red-Black trees and provided by Andrew Appel has +been adapted for the standard library by Pierre Letouzey. In the library +of real analysis, Yves Bertot changed the definition of :math:`\pi` and +provided a proof of the long-standing fact yet remaining unproved in +this library, namely that :math:`sin \frac{\pi}{2} = +1`. + +Pierre Corbineau maintained the Mathematical Proof Language (C-zar). + +Bruno Barras and Benjamin Grégoire maintained the call-by-value +reduction machines. + +The extraction mechanism benefited from several improvements provided by +Pierre Letouzey. + +Pierre Letouzey maintained the module system, with contributions from +Élie Soubiran. + +Julien Forest maintained the Function command. + +Matthieu Sozeau maintained the setoid rewriting mechanism. + +Coq related tools have been upgraded too. In particular, coq\_makefile +has been largely revised by Pierre Boutillier. Also, patches from Adam +Chlipala for coqdoc have been integrated by Pierre Boutillier. + +Bruno Barras and Pierre Letouzey maintained the `coqchk` checker. + +Pierre Courtieu and Arnaud Spiwack contributed new features for using +Coq through Proof General. + +The Dp plugin has been removed. Use the plugin provided with Why 3 +instead (http://why3.lri.fr/). + +Under the hood, the |Coq| architecture benefited from improvements in +terms of efficiency and robustness, especially regarding universes +management and existential variables management, thanks to Pierre +Letouzey and Yann Régis-Gianas with contributions from Stéphane Glondu +and Matthias Puech. The build system is maintained by Pierre Letouzey +with contributions from Stéphane Glondu and Pierre Boutillier. + +A new backtracking mechanism simplifying the task of external interfaces +has been designed by Pierre Letouzey. + +The general maintenance was done by Pierre Letouzey, Hugo Herbelin, +Pierre Boutillier, Matthieu Sozeau and Stéphane Glondu with also +specific contributions from Guillaume Melquiond, Julien Narboux and +Pierre-Marie Pédrot. + +Packaging tools were provided by Pierre Letouzey (Windows), Pierre +Boutillier (MacOS), Stéphane Glondu (Debian). Releasing, testing and +benchmarking support was provided by Jean-Marc Notin. + +Many suggestions for improvements were motivated by feedback from users, +on either the bug tracker or the Coq-Club mailing list. Special thanks +are going to the users who contributed patches, starting with Tom +Prince. Other patch contributors include Cédric Auger, David Baelde, Dan +Grayson, Paolo Herms, Robbert Krebbers, Marc Lasson, Hendrik Tews and +Eelis van der Weegen. + +| Paris, December 2011 +| Hugo Herbelin +| + +Potential sources of incompatibilities +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +The main known incompatibilities between 8.3 and 8.4 are consequences +of the following changes: + +- The reorganization of the library of numbers: + + Several definitions have new names or are defined in modules of + different names, but a special care has been taken to have this + renaming transparent for the user thanks to compatibility notations. + + However some definitions have changed, what might require some + adaptations. The most noticeable examples are: + + + The "?=" notation which now bind to Pos.compare rather than former + Pcompare (now Pos.compare_cont). + + Changes in names may induce different automatically generated + names in proof scripts (e.g. when issuing "destruct Z_le_gt_dec"). + + Z.add has a new definition, hence, applying "simpl" on subterms of + its body might give different results than before. + + BigN.shiftl and BigN.shiftr have reversed arguments order, the + power function in BigN now takes two BigN. + +- Other changes in libraries: + + + The definition of functions over "vectors" (list of fixed length) + have changed. + + TheoryList.v has been removed. + +- Slight changes in tactics: + + + Less unfolding of fixpoints when applying destruct or inversion on + a fixpoint hiding an inductive type (add an extra call to simpl to + preserve compatibility). + + Less unexpected local definitions when applying "destruct" + (incompatibilities solvable by adapting name hypotheses). + + Tactic "apply" might succeed more often, e.g. by now solving + pattern-matching of the form ?f x y = g(x,y) (compatibility + ensured by using "Unset Tactic Pattern Unification"), but also + because it supports (full) betaiota (using "simple apply" might + then help). + + Tactic autorewrite does no longer instantiate pre-existing + existential variables. + + Tactic "info" is now available only for auto, eauto and trivial. + +- Miscellaneous changes: + + + The command "Load" is now atomic for backtracking (use "Unset + Atomic Load" for compatibility). + +Details of changes in 8.4beta +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Logic + +- Standard eta-conversion now supported (dependent product only). +- Guard condition improvement: subterm property is propagated through beta-redex + blocked by pattern-matching, as in "(match v with C .. => fun x => u end) x"; + this allows for instance to use "rewrite ... in ..." without breaking + the guard condition. + +Specification language and notations + +- Maximal implicit arguments can now be set locally by { }. The registration + traverses fixpoints and lambdas. Because there is conversion in types, + maximal implicit arguments are not taken into account in partial + applications (use eta expanded form with explicit { } instead). +- Added support for recursive notations with binders (allows for instance + to write "exists x y z, P"). +- Structure/Record printing can be disable by "Unset Printing Records". + In addition, it can be controlled on type by type basis using + "Add Printing Record" or "Add Printing Constructor". +- Pattern-matching compilation algorithm: in "match x, y with ... end", + possible dependencies of x (or of the indices of its type) in the type + of y are now taken into account. + +Tactics + +- New proof engine. +- Scripts can now be structured thanks to bullets - * + and to subgoal + delimitation via { }. Note: for use with Proof General, a cvs version of + Proof General no older than mid-July 2011 is currently required. +- Support for tactical "info" is suspended. +- Support for command "Show Script" is suspended. +- New tactics constr_eq, is_evar and has_evar for use in Ltac (DOC TODO). +- Removed the two-argument variant of "decide equality". +- New experimental tactical "timeout <n> <tac>". Since <n> is a time + in second for the moment, this feature should rather be avoided + in scripts meant to be machine-independent. +- Fix in "destruct": removal of unexpected local definitions in context might + result in some rare incompatibilities (solvable by adapting name hypotheses). +- Introduction pattern "_" made more robust. +- Tactic (and Eval command) vm_compute can now be interrupted via Ctrl-C. +- Unification in "apply" supports unification of patterns of the form + ?f x y = g(x,y) (compatibility ensured by using + "Unset Tactic Pattern Unification"). It also supports (full) betaiota. +- Tactic autorewrite does no longer instantiate pre-existing + existential variables (theoretical source of possible incompatibilities). +- Tactic "dependent rewrite" now supports equality in "sig". +- Tactic omega now understands Zpred (wish #1912) and can prove any goal + from a context containing an arithmetical contradiction (wish #2236). +- Using "auto with nocore" disables the use of the "core" database (wish #2188). + This pseudo-database "nocore" can also be used with trivial and eauto. +- Tactics "set", "destruct" and "induction" accepts incomplete terms and + use the goal to complete the pattern assuming it is non ambiguous. +- When used on arguments with a dependent type, tactics such as + "destruct", "induction", "case", "elim", etc. now try to abstract + automatically the dependencies over the arguments of the types + (based on initial ideas from Chung-Kil Hur, extension to nested + dependencies suggested by Dan Grayson) +- Tactic "injection" now failing on an equality showing no constructors while + it was formerly generalizing again the goal over the given equality. +- In Ltac, the "context [...]" syntax has now a variant "appcontext [...]" + allowing to match partial applications in larger applications. +- When applying destruct or inversion on a fixpoint hiding an inductive + type, recursive calls to the fixpoint now remain folded by default (rare + source of incompatibility generally solvable by adding a call to simpl). +- In an ltac pattern containing a "match", a final "| _ => _" branch could be + used now instead of enumerating all remaining constructors. Moreover, the + pattern "match _ with _ => _ end" now allows to match any "match". A "in" + annotation can also be added to restrict to a precise inductive type. +- The behavior of "simpl" can be tuned using the "Arguments" vernacular. + In particular constants can be marked so that they are always/never unfolded + by "simpl", or unfolded only when a set of arguments evaluates to a + constructor. Last one can mark a constant so that it is unfolded only if the + simplified term does not expose a match in head position. + +Vernacular commands + +- It is now mandatory to have a space (or tabulation or newline or end-of-file) + after a "." ending a sentence. +- In SearchAbout, the [ ] delimiters are now optional. +- New command "Add/Remove Search Blacklist <substring> ...": + a Search or SearchAbout or similar query will never mention lemmas + whose qualified names contain any of the declared substrings. + The default blacklisted substrings are ``_subproof``, ``Private_``. +- When the output file of "Print Universes" ends in ".dot" or ".gv", + the universe graph is printed in the DOT language, and can be + processed by Graphviz tools. +- New command "Print Sorted Universes". +- The undocumented and obsolete option "Set/Unset Boxed Definitions" has + been removed, as well as syntaxes like "Boxed Fixpoint foo". +- A new option "Set Default Timeout n / Unset Default Timeout". +- Qed now uses information from the reduction tactics used in proof script + to avoid conversion at Qed time to go into a very long computation. +- New command "Show Goal ident" to display the statement of a goal, even + a closed one (available from Proof General). +- Command "Proof" accept a new modifier "using" to force generalization + over a given list of section variables at section ending (DOC TODO). +- New command "Arguments" generalizing "Implicit Arguments" and + "Arguments Scope" and that also allows to rename the parameters of a + definition and to tune the behavior of the tactic "simpl". + +Module System + +- During subtyping checks, an opaque constant in a module type could now + be implemented by anything of the right type, even if bodies differ. + Said otherwise, with respect to subtyping, an opaque constant behaves + just as a parameter. Coqchk was already implementing this, but not coqtop. +- The inlining done during application of functors can now be controlled + more precisely, by the annotations (no inline) or (inline at level XX). + With the latter annotation, only functor parameters whose levels + are lower or equal than XX will be inlined. + The level of a parameter can be fixed by "Parameter Inline(30) foo". + When levels aren't given, the default value is 100. One can also use + the flag "Set Inline Level ..." to set a level (DOC TODO). +- Print Assumptions should now handle correctly opaque modules (#2168). +- Print Module (Type) now tries to print more details, such as types and + bodies of the module elements. Note that Print Module Type could be + used on a module to display only its interface. The option + "Set Short Module Printing" could be used to switch back to the earlier + behavior were only field names were displayed. + +Libraries + +- Extension of the abstract part of Numbers, which now provide axiomatizations + and results about many more integer functions, such as pow, gcd, lcm, sqrt, + log2 and bitwise functions. These functions are implemented for nat, N, BigN, + Z, BigZ. See in particular file NPeano for new functions about nat. + +- The definition of types positive, N, Z is now in file BinNums.v + +- Major reorganization of ZArith. The initial file ZArith/BinInt.v now contains + an internal module Z implementing the Numbers interface for integers. + This module Z regroups: + + * all functions over type Z : Z.add, Z.mul, ... + * the minimal proofs of specifications for these functions : Z.add_0_l, ... + * an instantation of all derived properties proved generically in Numbers : + Z.add_comm, Z.add_assoc, ... + + A large part of ZArith is now simply compatibility notations, for instance + Zplus_comm is an alias for Z.add_comm. The direct use of module Z is now + recommended instead of relying on these compatibility notations. + +- Similar major reorganization of NArith, via a module N in NArith/BinNat.v + +- Concerning the positive datatype, BinPos.v is now in a specific directory + PArith, and contains an internal submodule Pos. We regroup there functions + such as Pos.add Pos.mul etc as well as many results about them. These results + are here proved directly (no Number interface for strictly positive numbers). + +- Note that in spite of the compatibility layers, all these reorganizations + may induce some marginal incompatibilies in scripts. In particular: + + * the "?=" notation for positive now refers to a binary function Pos.compare, + instead of the infamous ternary Pcompare (now Pos.compare_cont). + * some hypothesis names generated by the system may changed (typically for + a "destruct Z_le_gt_dec") since naming is done after the short name of + the head predicate (here now "le" in module Z instead of "Zle", etc). + * the internals of Z.add has changed, now relying of Z.pos_sub. + +- Also note these new notations: + + * "<?" "<=?" "=?" for boolean tests such as Z.ltb Z.leb Z.eqb. + * "÷" for the alternative integer division Z.quot implementing the Truncate + convention (former ZOdiv), while the notation for the Coq usual division + Z.div implementing the Flooring convention remains "/". Their corresponding + modulo functions are Z.rem (no notations) for Z.quot and Z.modulo (infix + "mod" notation) for Z.div. + +- Lemmas about conversions between these datatypes are also organized + in modules, see for instance modules Z2Nat, N2Z, etc. + +- When creating BigN, the macro-generated part NMake_gen is much smaller. + The generic part NMake has been reworked and improved. Some changes + may introduce incompatibilities. In particular, the order of the arguments + for BigN.shiftl and BigN.shiftr is now reversed: the number to shift now + comes first. By default, the power function now takes two BigN. + +- Creation of Vector, an independent library for lists indexed by their length. + Vectors' names overwrite lists' one so you should not "Import" the library. + All old names changed: function names follow the ocaml ones and, for example, + Vcons becomes Vector.cons. You can get [..;..;..]-style notations by importing + Vector.VectorNotations. + +- Removal of TheoryList. Requiring List instead should work most of the time. + +- New syntax "rew Heq in H" and "rew <- Heq in H" for eq_rect and + eq_rect_r (available by importing module EqNotations). + +- Wf.iter_nat is now Peano.nat_iter (with an implicit type argument). + +Internal infrastructure + +- Opaque proofs are now loaded lazily by default. This allows to be almost as + fast as -dont-load-proofs, while being safer (no creation of axioms) and + avoiding feature restrictions (Print and Print Assumptions work ok). +- Revised hash-consing code allowing more sharing of memory +- Experimental support added for camlp4 (the one provided alongside ocaml), + simply pass option -usecamlp4 to ./configure. By default camlp5 is used. +- Revised build system: no more stages in Makefile thanks to some recursive + aspect of recent gnu make, use of vo.itarget files containing .v to compile + for both make and ocamlbuild, etc. +- Support of cross-compilation via mingw from unix toward Windows, + contact P. Letouzey for more informations. +- New Makefile rules mli-doc to make html of mli in dev/doc/html and + full-stdlib to get a (huge) pdf reflecting the whole standard library. + +Extraction + +- By default, opaque terms are now truly considered opaque by extraction: + instead of accessing their body, they are now considered as axioms. + The previous behaviour can be reactivated via the option + "Set Extraction AccessOpaque". +- The pretty-printer for Haskell now produces layout-independent code +- A new command "Separate Extraction cst1 cst2 ..." that mixes a + minimal extracted environment a la "Recursive Extraction" and the + production of several files (one per coq source) a la "Extraction Library" + (DOC TODO). +- New option "Set/Unset Extraction KeepSingleton" for preventing the + extraction to optimize singleton container types (DOC TODO). +- The extraction now identifies and properly rejects a particular case of + universe polymorphism it cannot handle yet (the pair (I,I) being Prop). +- Support of anonymous fields in record (#2555). + +CoqIDE + +- Coqide now runs coqtop as separated process, making it more robust: + coqtop subprocess can be interrupted, or even killed and relaunched + (cf button "Restart Coq", ex-"Go to Start"). For allowing such + interrupts, the Windows version of coqide now requires Windows >= XP + SP1. +- The communication between CoqIDE and Coqtop is now done via a dialect + of XML (DOC TODO). +- The backtrack engine of CoqIDE has been reworked, it now uses the + "Backtrack" command similarly to Proof General. +- The Coqide parsing of sentences has be reworked and now supports + tactic delimitation via { }. +- Coqide now accepts the Abort command (wish #2357). +- Coqide can read coq_makefile files as "project file" and use it to + set automatically options to send to coqtop. +- Preference files have moved to $XDG_CONFIG_HOME/coq and accelerators + are not stored as a list anymore. + +Tools + +- Coq now searches directories specified in COQPATH, $XDG_DATA_HOME/coq, + $XDG_DATA_DIRS/coq, and user-contribs before the standard library. + +- Coq rc file has moved to $XDG_CONFIG_HOME/coq. + +- Major changes to coq_makefile: + + * mli/mlpack/mllib taken into account, ml not preproccessed anymore, ml4 work; + * mlihtml generates doc of mli, install-doc install the html doc in DOCDIR + with the same policy as vo in COQLIB; + * More variables are given by coqtop -config, others are defined only if the + users doesn't have defined them elsewhere. Consequently, generated makefile + should work directly on any architecture; + * Packagers can take advantage of $(DSTROOT) introduction. Installation can + be made in $XDG_DATA_HOME/coq; + * -arg option allows to send option as argument to coqc. + +Details of changes in 8.4beta2 +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Vernacular commands + +- Commands "Back" and "BackTo" are now handling the proof states. They may + perform some extra steps of backtrack to avoid states where the proof + state is unavailable (typically a closed proof). +- The commands "Suspend" and "Resume" have been removed. +- A basic Show Script has been reintroduced (no indentation). +- New command "Set Parsing Explicit" for deactivating parsing (and printing) + of implicit arguments (useful for teaching). +- New command "Grab Existential Variables" to transform the unresolved evars + at the end of a proof into goals. + +Tactics + +- Still no general "info" tactical, but new specific tactics info_auto, + info_eauto, info_trivial which provides information on the proofs found + by auto/eauto/trivial. Display of these details could also be activated by + "Set Info Auto"/"Set Info Eauto"/"Set Info Trivial". +- Details on everything tried by auto/eauto/trivial during a proof search + could be obtained by "debug auto", "debug eauto", "debug trivial" or by a + global "Set Debug Auto"/"Set Debug Eauto"/"Set Debug Trivial". +- New command "r string" in Ltac debugger that interprets "idtac + string" in Ltac code as a breakpoint and jumps to its next use. +- Tactics from the Dp plugin (simplify, ergo, yices, cvc3, z3, cvcl, + harvey, zenon, gwhy) have been removed, since Why2 has not been + maintained for the last few years. The Why3 plugin should be a suitable + replacement in most cases. + +Libraries + +- MSetRBT: a new implementation of MSets via Red-Black trees (initial + contribution by Andrew Appel). +- MSetAVL: for maximal sharing with the new MSetRBT, the argument order + of Node has changed (this should be transparent to regular MSets users). + +Module System + +- The names of modules (and module types) are now in a fully separated + namespace from ordinary definitions: "Definition E:=0. Module E. End E." + is now accepted. + +CoqIDE + +- Coqide now supports the "Restart" command, and "Undo" (with a warning). + Better support for "Abort". + +Details of changes in 8.4 +~~~~~~~~~~~~~~~~~~~~~~~~~ + +Vernacular commands + +- The "Reset" command is now supported again in files given to coqc or Load. +- "Show Script" now indents again the displayed scripts. It can also work + correctly across Load'ed files if the option "Unset Atomic Load" is used. +- "Open Scope" can now be given the delimiter (e.g. Z) instead of the full + scope name (e.g. Z_scope). + +Notations + +- Most compatibility notations of the standard library are now tagged as + (compat xyz), where xyz is a former Coq version, for instance "8.3". + These notations behave as (only parsing) notations, except that they may + triggers warnings (or errors) when used while Coq is not in a corresponding + -compat mode. +- To activate these compatibility warnings, use "Set Verbose Compat Notations" + or the command-line flag -verbose-compat-notations. +- For a strict mode without these compatibility notations, use + "Unset Compat Notations" or the command-line flag -no-compat-notations. + +Tactics + +- An annotation "eqn:H" or "eqn:?" can be added to a "destruct" + or "induction" to make it generate equations in the spirit of "case_eq". + The former syntax "_eqn" is discontinued. +- The name of the hypothesis introduced by tactic "remember" can be + set via the new syntax "remember t as x eqn:H" (wish #2489). + +Libraries + +- Reals: changed definition of PI, no more axiom about sin(PI/2). +- SetoidPermutation: a notion of permutation for lists modulo a setoid equality. +- BigN: fixed the ocaml code doing the parsing/printing of big numbers. +- List: a couple of lemmas added especially about no-duplication, partitions. +- Init: Removal of the coercions between variants of sigma-types and + subset types (possible source of incompatibility). + +Version 8.3 +----------- + +Summary of changes +~~~~~~~~~~~~~~~~~~ + +Coq version 8.3 is before all a transition version with refinements or +extensions of the existing features and libraries and a new tactic nsatz +based on Hilbert’s Nullstellensatz for deciding systems of equations +over rings. + +With respect to libraries, the main evolutions are due to Pierre +Letouzey with a rewriting of the library of finite sets FSets and a new +round of evolutions in the modular development of arithmetic (library +Numbers). The reason for making FSets evolve is that the computational +and logical contents were quite intertwined in the original +implementation, leading in some cases to longer computations than +expected and this problem is solved in the new MSets implementation. As +for the modular arithmetic library, it was only dealing with the basic +arithmetic operators in the former version and its current extension +adds the standard theory of the division, min and max functions, all +made available for free to any implementation of :math:`\mathbb{N}`, +:math:`\mathbb{Z}` or :math:`\mathbb{Z}/n\mathbb{Z}`. + +The main other evolutions of the library are due to Hugo Herbelin who +made a revision of the sorting library (including a certified +merge-sort) and to Guillaume Melquiond who slightly revised and cleaned +up the library of reals. + +The module system evolved significantly. Besides the resolution of some +efficiency issues and a more flexible construction of module types, Élie +Soubiran brought a new model of name equivalence, the +:math:`\Delta`-equivalence, which respects as much as possible the names +given by the users. He also designed with Pierre Letouzey a new, +convenient operator ``<+`` for nesting functor application that +provides a light notation for inheriting the properties of cascading +modules. + +The new tactic nsatz is due to Loïc Pottier. It works by computing +Gröbner bases. Regarding the existing tactics, various improvements have +been done by Matthieu Sozeau, Hugo Herbelin and Pierre Letouzey. + +Matthieu Sozeau extended and refined the typeclasses and Program +features (the Russell language). Pierre Letouzey maintained and improved +the extraction mechanism. Bruno Barras and Élie Soubiran maintained the +Coq checker, Julien Forest maintained the Function mechanism for +reasoning over recursively defined functions. Matthieu Sozeau, Hugo +Herbelin and Jean-Marc Notin maintained coqdoc. Frédéric Besson +maintained the Micromega platform for deciding systems of inequalities. +Pierre Courtieu maintained the support for the Proof General Emacs +interface. Claude Marché maintained the plugin for calling external +provers (dp). Yves Bertot made some improvements to the libraries of +lists and integers. Matthias Puech improved the search functions. +Guillaume Melquiond usefully contributed here and there. Yann +Régis-Gianas grounded the support for Unicode on a more standard and +more robust basis. + +Though invisible from outside, Arnaud Spiwack improved the general +process of management of existential variables. Pierre Letouzey and +Stéphane Glondu improved the compilation scheme of the |Coq| archive. +Vincent Gross provided support to |CoqIDE|. Jean-Marc Notin provided +support for benchmarking and archiving. + +Many users helped by reporting problems, providing patches, suggesting +improvements or making useful comments, either on the bug tracker or on +the Coq-Club mailing list. This includes but not exhaustively Cédric +Auger, Arthur Charguéraud, François Garillot, Georges Gonthier, Robin +Green, Stéphane Lescuyer, Eelis van der Weegen, ... + +Though not directly related to the implementation, special thanks are +going to Yves Bertot, Pierre Castéran, Adam Chlipala, and Benjamin +Pierce for the excellent teaching materials they provided. + +| Paris, April 2010 +| Hugo Herbelin +| + +Details of changes +~~~~~~~~~~~~~~~~~~ + +Rewriting tactics + +- Tactic "rewrite" now supports rewriting on ad hoc equalities such as eq_true. +- "Hint Rewrite" now checks that the lemma looks like an equation. +- New tactic "etransitivity". +- Support for heterogeneous equality (JMeq) in "injection" and "discriminate". +- Tactic "subst" now supports heterogeneous equality and equality + proofs that are dependent (use "simple subst" for preserving compatibility). +- Added support for Leibniz-rewriting of dependent hypotheses. +- Renamed "Morphism" into "Proper" and "respect" into "proper_prf" + (possible source of incompatibility). A partial fix is to define + "Notation Morphism R f := (Proper (R%signature) f)." +- New tactic variants "rewrite* by" and "autorewrite*" that rewrite + respectively the first and all matches whose side-conditions are + solved. +- "Require Import Setoid" does not export all of "Morphisms" and + "RelationClasses" anymore (possible source of incompatibility, fixed + by importing "Morphisms" too). +- Support added for using Chung-Kil Hur's Heq library for rewriting over + heterogeneous equality (courtesy of the library's author). +- Tactic "replace" supports matching terms with holes. + +Automation tactics + +- Tactic ``intuition`` now preserves inner ``iff`` and ``not`` (exceptional + source of incompatibilities solvable by redefining ``intuition`` as + ``unfold iff, not in *; intuition``, or, for iff only, by using + ``Set Intuition Iff Unfolding``.) +- Tactic ``tauto`` now proves classical tautologies as soon as classical logic + (i.e. library ``Classical_Prop`` or ``Classical``) is loaded. +- Tactic ``gappa`` has been removed from the Dp plugin. +- Tactic ``firstorder`` now supports the combination of its ``using`` and + ``with`` options. +- New ``Hint Resolve ->`` (or ``<-``) for declaring iff's as oriented + hints (wish #2104). +- An inductive type as argument of the ``using`` option of ``auto`` / ``eauto`` / ``firstorder`` + is interpreted as using the collection of its constructors. +- New decision tactic "nsatz" to prove polynomial equations + by computation of Groebner bases. + +Other tactics + +- Tactic "discriminate" now performs intros before trying to discriminate an + hypothesis of the goal (previously it applied intro only if the goal + had the form t1<>t2) (exceptional source of incompatibilities - former + behavior can be obtained by "Unset Discriminate Introduction"). +- Tactic "quote" now supports quotation of arbitrary terms (not just the + goal). +- Tactic "idtac" now displays its "list" arguments. +- New introduction patterns "*" for introducing the next block of dependent + variables and "**" for introducing all quantified variables and hypotheses. +- Pattern Unification for existential variables activated in tactics and + new option "Unset Tactic Evars Pattern Unification" to deactivate it. +- Resolution of canonical structure is now part of the tactic's unification + algorithm. +- New tactic "decide lemma with hyp" for rewriting decidability lemmas + when one knows which side is true. +- Improved support of dependent goals over objects in dependent types for + "destruct" (rare source of incompatibility that can be avoided by unsetting + option "Dependent Propositions Elimination"). +- Tactic "exists", "eexists", "destruct" and "edestruct" supports iteration + using comma-separated arguments. +- Tactic names "case" and "elim" now support clauses "as" and "in" and become + then synonymous of "destruct" and "induction" respectively. +- A new tactic name "exfalso" for the use of 'ex-falso quodlibet' principle. + This tactic is simply a shortcut for "elimtype False". +- Made quantified hypotheses get the name they would have if introduced in + the context (possible but rare source of incompatibilities). +- When applying a component of a conjunctive lemma, "apply in" (and + sequences of "apply in") now leave the side conditions of the lemmas + uniformly after the main goal (possible source of rare incompatibilities). +- In "simpl c" and "change c with d", c can be a pattern. +- Tactic "revert" now preserves let-in's making it the exact inverse of + "intro". +- New tactics "clear dependent H" and "revert dependent H" that + clears (resp. reverts) H and all the hypotheses that depend on H. +- Ltac's pattern-matching now supports matching metavariables that + depend on variables bound upwards in the pattern. + +Tactic definitions + +- Ltac definitions support Local option for non-export outside modules. +- Support for parsing non-empty lists with separators in tactic notations. +- New command "Locate Ltac" to get the full name of an Ltac definition. + +Notations + +- Record syntax ``{|x=...; y=...|}`` now works inside patterns too. +- Abbreviations from non-imported module now invisible at printing time. +- Abbreviations now use implicit arguments and arguments scopes for printing. +- Abbreviations to pure names now strictly behave like the name they refer to + (make redirections of qualified names easier). +- Abbreviations for applied constant now propagate the implicit arguments + and arguments scope of the underlying reference (possible source of + incompatibilities generally solvable by changing such abbreviations from + e.g. ``Notation foo' := (foo x)`` to ``Notation foo' y := (foo x (y:=y))``). +- The "where" clause now supports multiple notations per defined object. +- Recursive notations automatically expand one step on the left for better + factorization; recursion notations inner separators now ensured being tokens. +- Added "Reserved Infix" as a specific shortcut of the corresponding + "Reserved Notation". +- Open/Close Scope command supports Global option in sections. + +Specification language + +- New support for local binders in the syntax of Record/Structure fields. +- Fixpoint/CoFixpoint now support building part or all of bodies using tactics. +- Binders given before ":" in lemmas and in definitions built by tactics are + now automatically introduced (possible source of incompatibility that can + be resolved by invoking "Unset Automatic Introduction"). +- New support for multiple implicit arguments signatures per reference. + +Module system + +- Include Type is now deprecated since Include now accept both modules and + module types. +- Declare ML Module supports Local option. +- The sharing between non-logical object and the management of the + name-space has been improved by the new "Delta-equivalence" on + qualified name. +- The include operator has been extended to high-order structures +- Sequences of Include can be abbreviated via new syntax "<+". +- A module (or module type) can be given several "<:" signatures. +- Interactive proofs are now permitted in module type. Functors can hence + be declared as Module Type and be used later to type themselves. +- A functor application can be prefixed by a "!" to make it ignore any + "Inline" annotation in the type of its argument(s) (for examples of + use of the new features, see libraries Structures and Numbers). +- Coercions are now active only when modules are imported (use "Set Automatic + Coercions Import" to get the behavior of the previous versions of Coq). + +Extraction + +- When using (Recursive) Extraction Library, the filenames are directly the + Coq ones with new appropriate extensions : we do not force anymore + uncapital first letters for Ocaml and capital ones for Haskell. +- The extraction now tries harder to avoid code transformations that can be + dangerous for the complexity. In particular many eta-expansions at the top + of functions body are now avoided, clever partial applications will likely + be preserved, let-ins are almost always kept, etc. +- In the same spirit, auto-inlining is now disabled by default, except for + induction principles, since this feature was producing more frequently + weird code than clear gain. The previous behavior can be restored via + "Set Extraction AutoInline". +- Unicode characters in identifiers are now transformed into ascii strings + that are legal in Ocaml and other languages. +- Harsh support of module extraction to Haskell and Scheme: module hierarchy + is flattened, module abbreviations and functor applications are expanded, + module types and unapplied functors are discarded. +- Less unsupported situations when extracting modules to Ocaml. In particular + module parameters might be alpha-renamed if a name clash is detected. +- Extract Inductive is now possible toward non-inductive types (e.g. nat => int) +- Extraction Implicit: this new experimental command allows to mark + some arguments of a function or constructor for removed during + extraction, even if these arguments don't fit the usual elimination + principles of extraction, for instance the length n of a vector. +- Files ExtrOcaml*.v in plugins/extraction try to provide a library of common + extraction commands: mapping of basics types toward Ocaml's counterparts, + conversions from/to int and big_int, or even complete mapping of nat,Z,N + to int or big_int, or mapping of ascii to char and string to char list + (in this case recognition of ascii constants is hard-wired in the extraction). + +Program + +- Streamlined definitions using well-founded recursion and measures so + that they can work on any subset of the arguments directly (uses currying). +- Try to automatically clear structural fixpoint prototypes in + obligations to avoid issues with opacity. +- Use return type clause inference in pattern-matching as in the standard + typing algorithm. +- Support [Local Obligation Tactic] and [Next Obligation with tactic]. +- Use [Show Obligation Tactic] to print the current default tactic. +- [fst] and [snd] have maximal implicit arguments in Program now (possible + source of incompatibility). + +Type classes + +- Declaring axiomatic type class instances in Module Type should be now + done via new command "Declare Instance", while the syntax "Instance" + now always provides a concrete instance, both in and out of Module Type. +- Use [Existing Class foo] to declare foo as a class a posteriori. + [foo] can be an inductive type or a constant definition. No + projections or instances are defined. +- Various bug fixes and improvements: support for defined fields, + anonymous instances, declarations giving terms, better handling of + sections and [Context]. + +Vernacular commands + +- New command "Timeout <n> <command>." interprets a command and a timeout + interrupts the interpretation after <n> seconds. +- New command "Compute <expr>." is a shortcut for "Eval vm_compute in <expr>". +- New command "Fail <command>." interprets a command and is successful iff + the command fails on an error (but not an anomaly). Handy for tests and + illustration of wrong commands. +- Most commands referring to constant (e.g. Print or About) now support + referring to the constant by a notation string. +- New option "Boolean Equality Schemes" to make generation of boolean + equality automatic for datatypes (together with option "Decidable + Equality Schemes", this replaces deprecated option "Equality Scheme"). +- Made support for automatic generation of case analysis schemes available + to user (governed by option "Set Case Analysis Schemes"). +- New command :n:`{? Global } Generalizable [All|No] [Variable|Variables] {* @ident}` to + declare which identifiers are generalizable in `` `{} `` and `` `() `` binders. +- New command "Print Opaque Dependencies" to display opaque constants in + addition to all variables, parameters or axioms a theorem or + definition relies on. +- New command "Declare Reduction <id> := <conv_expr>", allowing to write + later "Eval <id> in ...". This command accepts a Local variant. +- Syntax of Implicit Type now supports more than one block of variables of + a given type. +- Command "Canonical Structure" now warns when it has no effects. +- Commands of the form "Set X" or "Unset X" now support "Local" and "Global" + prefixes. + +Library + +- Use "standard" Coq names for the properties of eq and identity + (e.g. refl_equal is now eq_refl). Support for compatibility is provided. + +- The function Compare_dec.nat_compare is now defined directly, + instead of relying on lt_eq_lt_dec. The earlier version is still + available under the name nat_compare_alt. + +- Lemmas in library Relations and Reals have been homogenized a bit. + +- The implicit argument of Logic.eq is now maximally inserted, allowing + to simply write "eq" instead of "@eq _" in morphism signatures. + +- Wrongly named lemmas (Zlt_gt_succ and Zlt_succ_gt) fixed (potential source + of incompatibilities) + +- List library: + + + Definitions of list, length and app are now in Init/Datatypes. + Support for compatibility is provided. + + Definition of Permutation is now in Sorting/Permtation.v + + Some other light revisions and extensions (possible source + of incompatibilities solvable by qualifying names accordingly). + +- In ListSet, set_map has been fixed (source of incompatibilities if used). + +- Sorting library: + + + new mergesort of worst-case complexity O(n*ln(n)) made available in + Mergesort.v; + + former notion of permutation up to setoid from Permutation.v is + deprecated and moved to PermutSetoid.v; + + heapsort from Heap.v of worst-case complexity O(n*n) is deprecated; + + new file Sorted.v for some definitions of being sorted. + +- Structure library. This new library is meant to contain generic + structures such as types with equalities or orders, either + in Module version (for now) or Type Classes (still to do): + + + DecidableType.v and OrderedType.v: initial notions for FSets/FMaps, + left for compatibility but considered as deprecated. + + Equalities.v and Orders.v: evolutions of the previous files, + with fine-grain Module architecture, many variants, use of + Equivalence and other relevant Type Classes notions. + + OrdersTac.v: a generic tactic for solving chains of (in)equalities + over variables. See {Nat,N,Z,P}OrderedType.v for concrete instances. + + GenericMinMax.v: any ordered type can be equipped with min and max. + We derived here all the generic properties of these functions. + +- MSets library: an important evolution of the FSets library. + "MSets" stands for Modular (Finite) Sets, by contrast with a forthcoming + library of Class (Finite) Sets contributed by S. Lescuyer which will be + integrated with the next release of Coq. The main features of MSets are: + + + The use of Equivalence, Proper and other Type Classes features + easing the handling of setoid equalities. + + The interfaces are now stated in iff-style. Old specifications + are now derived properties. + + The compare functions are now pure, and return a "comparison" value. + Thanks to the CompSpec inductive type, reasoning on them remains easy. + + Sets structures requiring invariants (i.e. sorted lists) are + built first as "Raw" sets (pure objects and separate proofs) and + attached with their proofs thanks to a generic functor. "Raw" sets + have now a proper interface and can be manipulated directly. + + Note: No Maps yet in MSets. The FSets library is still provided + for compatibility, but will probably be considered as deprecated in the + next release of Coq. + +- Numbers library: + + + The abstract layer (NatInt, Natural/Abstract, Integer/Abstract) has + been simplified and enhance thanks to new features of the module + system such as Include (see above). It has been extended to Euclidean + division (three flavors for integers: Trunc, Floor and Math). + + The arbitrary-large efficient numbers (BigN, BigZ, BigQ) has also + been reworked. They benefit from the abstract layer improvements + (especially for div and mod). Note that some specifications have + slightly changed (compare, div, mod, shift{r,l}). Ring/Field should + work better (true recognition of constants). + +Tools + +- Option -R now supports binding Coq root read-only. +- New coqtop/coqc option -beautify to reformat .v files (usable + e.g. to globally update notations). +- New tool beautify-archive to beautify a full archive of developments. +- New coqtop/coqc option -compat X.Y to simulate the general behavior + of previous versions of Coq (provides e.g. support for 8.2 compatibility). + +Coqdoc + +- List have been revamped. List depth and scope is now determined by + an "offside" whitespace rule. +- Text may be italicized by placing it in _underscores_. +- The "--index <string>" flag changes the filename of the index. +- The "--toc-depth <int>" flag limits the depth of headers which are + included in the table of contents. +- The "--lib-name <string>" flag prints "<string> Foo" instead of + "Library Foo" where library titles are called for. The + "--no-lib-name" flag eliminates the extra title. +- New option "--parse-comments" to allow parsing of regular ``(* *)`` + comments. +- New option "--plain-comments" to disable interpretation inside comments. +- New option "--interpolate" to try and typeset identifiers in Coq escapings + using the available globalization information. +- New option "--external url root" to refer to external libraries. +- Links to section variables and notations now supported. + +Internal infrastructure + +- To avoid confusion with the repository of user's contributions, + the subdirectory "contrib" has been renamed into "plugins". + On platforms supporting ocaml native dynlink, code located there + is built as loadable plugins for coqtop. +- An experimental build mechanism via ocamlbuild is provided. + From the top of the archive, run ./configure as usual, and + then ./build. Feedback about this build mechanism is most welcome. + Compiling Coq on platforms such as Windows might be simpler + this way, but this remains to be tested. +- The Makefile system has been simplified and factorized with + the ocamlbuild system. In particular "make" takes advantage + of .mllib files for building .cma/.cmxa. The .vo files to + compile are now listed in several vo.itarget files. + +Version 8.2 +----------- + +Summary of changes +~~~~~~~~~~~~~~~~~~ + +Coq version 8.2 adds new features, new libraries and improves on many +various aspects. + +Regarding the language of |Coq|, the main novelty is the introduction by +Matthieu Sozeau of a package of commands providing Haskell-style typeclasses. +Typeclasses, which come with a few convenient features such as +type-based resolution of implicit arguments, play a new landmark role +in the architecture of |Coq| with respect to automation. For +instance, thanks to typeclass support, Matthieu Sozeau could +implement a new resolution-based version of the tactics dedicated to +rewriting on arbitrary transitive relations. + +Another major improvement of |Coq| 8.2 is the evolution of the arithmetic +libraries and of the tools associated to them. Benjamin Grégoire and +Laurent Théry contributed a modular library for building arbitrarily +large integers from bounded integers while Evgeny Makarov contributed a +modular library of abstract natural and integer arithmetic together +with a few convenient tactics. On his side, Pierre Letouzey made +numerous extensions to the arithmetic libraries on :math:`\mathbb{Z}` +and :math:`\mathbb{Q}`, including extra support for automation in +presence of various number-theory concepts. + +Frédéric Besson contributed a reflective tactic based on Krivine-Stengle +Positivstellensatz (the easy way) for validating provability of systems +of inequalities. The platform is flexible enough to support the +validation of any algorithm able to produce a “certificate” for the +Positivstellensatz and this covers the case of Fourier-Motzkin (for +linear systems in :math:`\mathbb{Q}` and :math:`\mathbb{R}`), +Fourier-Motzkin with cutting planes (for linear systems in +:math:`\mathbb{Z}`) and sum-of-squares (for non-linear systems). Evgeny +Makarov made the platform generic over arbitrary ordered rings. + +Arnaud Spiwack developed a library of 31-bits machine integers and, +relying on Benjamin Grégoire and Laurent Théry’s library, delivered a +library of unbounded integers in base :math:`2^{31}`. As importantly, he +developed a notion of “retro-knowledge” so as to safely extend the +kernel-located bytecode-based efficient evaluation algorithm of |Coq| +version 8.1 to use 31-bits machine arithmetic for efficiently computing +with the library of integers he developed. + +Beside the libraries, various improvements were contributed to provide a more +comfortable end-user language and more expressive tactic language. Hugo +Herbelin and Matthieu Sozeau improved the pattern matching compilation +algorithm (detection of impossible clauses in pattern matching, +automatic inference of the return type). Hugo Herbelin, Pierre Letouzey +and Matthieu Sozeau contributed various new convenient syntactic +constructs and new tactics or tactic features: more inference of +redundant information, better unification, better support for proof or +definition by fixpoint, more expressive rewriting tactics, better +support for meta-variables, more convenient notations... + +Élie Soubiran improved the module system, adding new features (such as +an “include” command) and making it more flexible and more general. He +and Pierre Letouzey improved the support for modules in the extraction +mechanism. + +Matthieu Sozeau extended the Russell language, ending in an convenient +way to write programs of given specifications, Pierre Corbineau extended +the Mathematical Proof Language and the automation tools that +accompany it, Pierre Letouzey supervised and extended various parts of the +standard library, Stéphane Glondu contributed a few tactics and +improvements, Jean-Marc Notin provided help in debugging, general +maintenance and coqdoc support, Vincent Siles contributed extensions of +the Scheme command and of injection. + +Bruno Barras implemented the ``coqchk`` tool: this is a stand-alone +type checker that can be used to certify .vo files. Especially, as this +verifier runs in a separate process, it is granted not to be “hijacked” +by virtually malicious extensions added to |Coq|. + +Yves Bertot, Jean-Christophe Filliâtre, Pierre Courtieu and Julien +Forest acted as maintainers of features they implemented in previous +versions of |Coq|. + +Julien Narboux contributed to |CoqIDE|. Nicolas Tabareau made the +adaptation of the interface of the old “setoid rewrite” tactic to the +new version. Lionel Mamane worked on the interaction between |Coq| and its +external interfaces. With Samuel Mimram, he also helped making |Coq| +compatible with recent software tools. Russell O’Connor, Cezary +Kaliszyk, Milad Niqui contributed to improve the libraries of integers, +rational, and real numbers. We also thank many users and partners for +suggestions and feedback, in particular Pierre Castéran and Arthur +Charguéraud, the INRIA Marelle team, Georges Gonthier and the +INRIA-Microsoft Mathematical Components team, the Foundations group at +Radboud university in Nijmegen, reporters of bugs and participants to +the Coq-Club mailing list. + +| Palaiseau, June 2008 +| Hugo Herbelin +| + +Details of changes +~~~~~~~~~~~~~~~~~~ + +Language + +- If a fixpoint is not written with an explicit { struct ... }, then + all arguments are tried successively (from left to right) until one is + found that satisfies the structural decreasing condition. +- New experimental typeclass system giving ad-hoc polymorphism and + overloading based on dependent records and implicit arguments. +- New syntax "let 'pat := b in c" for let-binding using irrefutable patterns. +- New syntax "forall {A}, T" for specifying maximally inserted implicit + arguments in terms. +- Sort of Record/Structure, Inductive and CoInductive defaults to Type + if omitted. +- (Co)Inductive types can be defined as records + (e.g. "CoInductive stream := { hd : nat; tl : stream }.") +- New syntax "Theorem id1:t1 ... with idn:tn" for proving mutually dependent + statements. +- Support for sort-polymorphism on constants denoting inductive types. +- Several evolutions of the module system (handling of module aliases, + functorial module types, an Include feature, etc). +- Prop now a subtype of Set (predicative and impredicative forms). +- Recursive inductive types in Prop with a single constructor of which + all arguments are in Prop is now considered to be a singleton + type. It consequently supports all eliminations to Prop, Set and Type. + As a consequence, Acc_rect has now a more direct proof [possible source + of easily fixed incompatibility in case of manual definition of a recursor + in a recursive singleton inductive type]. + +Vernacular commands + +- Added option Global to "Arguments Scope" for section surviving. +- Added option "Unset Elimination Schemes" to deactivate the automatic + generation of elimination schemes. +- Modification of the Scheme command so you can ask for the name to be + automatically computed (e.g. Scheme Induction for nat Sort Set). +- New command "Combined Scheme" to build combined mutual induction + principles from existing mutual induction principles. +- New command "Scheme Equality" to build a decidable (boolean) equality + for simple inductive datatypes and a decision property over this equality + (e.g. Scheme Equality for nat). +- Added option "Set Equality Scheme" to make automatic the declaration + of the boolean equality when possible. +- Source of universe inconsistencies now printed when option + "Set Printing Universes" is activated. +- New option "Set Printing Existential Instances" for making the display of + existential variable instances explicit. +- Support for option "[id1 ... idn]", and "-[id1 ... idn]", for the + "compute"/"cbv" reduction strategy, respectively meaning reduce only, or + everything but, the constants id1 ... idn. "lazy" alone or followed by + "[id1 ... idn]", and "-[id1 ... idn]" also supported, meaning apply + all of beta-iota-zeta-delta, possibly restricting delta. +- New command "Strategy" to control the expansion of constants during + conversion tests. It generalizes commands Opaque and Transparent by + introducing a range of levels. Lower levels are assigned to constants + that should be expanded first. +- New options Global and Local to Opaque and Transparent. +- New command "Print Assumptions" to display all variables, parameters + or axioms a theorem or definition relies on. +- "Add Rec LoadPath" now provides references to libraries using partially + qualified names (this holds also for coqtop/coqc option -R). +- SearchAbout supports negated search criteria, reference to logical objects + by their notation, and more generally search of subterms. +- "Declare ML Module" now allows to import .cmxs files when Coq is + compiled in native code with a version of OCaml that supports native + Dynlink (>= 3.11). +- Specific sort constraints on Record now taken into account. +- "Print LoadPath" supports a path argument to filter the display. + +Libraries + +- Several parts of the libraries are now in Type, in particular FSets, + SetoidList, ListSet, Sorting, Zmisc. This may induce a few + incompatibilities. In case of trouble while fixing existing development, + it may help to simply declare Set as an alias for Type (see file + SetIsType). + +- New arithmetical library in theories/Numbers. It contains: + + * an abstract modular development of natural and integer arithmetics + in Numbers/Natural/Abstract and Numbers/Integer/Abstract + * an implementation of efficient computational bounded and unbounded + integers that can be mapped to processor native arithmetics. + See Numbers/Cyclic/Int31 for 31-bit integers and Numbers/Natural/BigN + for unbounded natural numbers and Numbers/Integer/BigZ for unbounded + integers. + * some proofs that both older libraries Arith, ZArith and NArith and + newer BigN and BigZ implement the abstract modular development. + This allows in particular BigN and BigZ to already come with a + large database of basic lemmas and some generic tactics (ring), + + This library has still an experimental status, as well as the + processor-acceleration mechanism, but both its abstract and its + concrete parts are already quite usable and could challenge the use + of nat, N and Z in actual developments. Moreover, an extension of + this framework to rational numbers is ongoing, and an efficient + Q structure is already provided (see Numbers/Rational/BigQ), but + this part is currently incomplete (no abstract layer and generic + lemmas). + +- Many changes in FSets/FMaps. In practice, compatibility with earlier + version should be fairly good, but some adaptations may be required. + + * Interfaces of unordered ("weak") and ordered sets have been factorized + thanks to new features of Coq modules (in particular Include), see + FSetInterface. Same for maps. Hints in these interfaces have been + reworked (they are now placed in a "set" database). + * To allow full subtyping between weak and ordered sets, a field + "eq_dec" has been added to OrderedType. The old version of OrderedType + is now called MiniOrderedType and functor MOT_to_OT allow to + convert to the new version. The interfaces and implementations + of sets now contain also such a "eq_dec" field. + * FSetDecide, contributed by Aaron Bohannon, contains a decision + procedure allowing to solve basic set-related goals (for instance, + is a point in a particular set ?). See FSetProperties for examples. + * Functors of properties have been improved, especially the ones about + maps, that now propose some induction principles. Some properties + of fold need less hypothesis. + * More uniformity in implementations of sets and maps: they all use + implicit arguments, and no longer export unnecessary scopes (see + bug #1347) + * Internal parts of the implementations based on AVL have evolved a + lot. The main files FSetAVL and FMapAVL are now much more + lightweight now. In particular, minor changes in some functions + has allowed to fully separate the proofs of operational + correctness from the proofs of well-balancing: well-balancing is + critical for efficiency, but not anymore for proving that these + trees implement our interfaces, hence we have moved these proofs + into appendix files FSetFullAVL and FMapFullAVL. Moreover, a few + functions like union and compare have been modified in order to be + structural yet efficient. The appendix files also contains + alternative versions of these few functions, much closer to the + initial Ocaml code and written via the Function framework. + +- Library IntMap, subsumed by FSets/FMaps, has been removed from + Coq Standard Library and moved into a user contribution Cachan/IntMap + +- Better computational behavior of some constants (eq_nat_dec and + le_lt_dec more efficient, Z_lt_le_dec and Positive_as_OT.compare + transparent, ...) (exceptional source of incompatibilities). + +- Boolean operators moved from module Bool to module Datatypes (may need + to rename qualified references in script and force notations || and && + to be at levels 50 and 40 respectively). + +- The constructors xI and xO of type positive now have postfix notations + "~1" and "~0", allowing to write numbers in binary form easily, for instance + 6 is 1~1~0 and 4*p is p~0~0 (see BinPos.v). + +- Improvements to NArith (Nminus, Nmin, Nmax), and to QArith (in particular + a better power function). + +- Changes in ZArith: several additional lemmas (used in theories/Numbers), + especially in Zdiv, Znumtheory, Zpower. Moreover, many results in + Zdiv have been generalized: the divisor may simply be non-null + instead of strictly positive (see lemmas with name ending by + "_full"). An alternative file ZOdiv proposes a different behavior + (the one of Ocaml) when dividing by negative numbers. + +- Changes in Arith: EqNat and Wf_nat now exported from Arith, some + constructions on nat that were outside Arith are now in (e.g. iter_nat). + +- In SetoidList, eqlistA now expresses that two lists have similar elements + at the same position, while the predicate previously called eqlistA + is now equivlistA (this one only states that the lists contain the same + elements, nothing more). + +- Changes in Reals: + + * Most statement in "sigT" (including the + completeness axiom) are now in "sig" (in case of incompatibility, + use proj1_sig instead of projT1, sig instead of sigT, etc). + * More uniform naming scheme (identifiers in French moved to English, + consistent use of 0 -- zero -- instead of O -- letter O --, etc). + * Lemma on prod_f_SO is now on prod_f_R0. + * Useless hypothesis of ln_exists1 dropped. + * New Rlogic.v states a few logical properties about R axioms. + * RIneq.v extended and made cleaner. + +- Slight restructuration of the Logic library regarding choice and classical + logic. Addition of files providing intuitionistic axiomatizations of + descriptions: Epsilon.v, Description.v and IndefiniteDescription.v. + +- Definition of pred and minus made compatible with the structural + decreasing criterion for use in fixpoints. + +- Files Relations/Rstar.v and Relations/Newman.v moved out to the user + contribution repository (contribution CoC_History). New lemmas about + transitive closure added and some bound variables renamed (exceptional + risk of incompatibilities). + +- Syntax for binders in terms (e.g. for "exists") supports anonymous names. + +Notations, coercions, implicit arguments and type inference + +- More automation in the inference of the return clause of dependent + pattern-matching problems. +- Experimental allowance for omission of the clauses easily detectable as + impossible in pattern-matching problems. +- Improved inference of implicit arguments. +- New options "Set Maximal Implicit Insertion", "Set Reversible Pattern + Implicit", "Set Strongly Strict Implicit" and "Set Printing Implicit + Defensive" for controlling inference and use of implicit arguments. +- New modifier in "Implicit Arguments" to force an implicit argument to + be maximally inserted. +- New modifier of "Implicit Arguments" to enrich the set of implicit arguments. +- New options Global and Local to "Implicit Arguments" for section + surviving or non export outside module. +- Level "constr" moved from 9 to 8. +- Structure/Record now printed as Record (unless option Printing All is set). +- Support for parametric notations defining constants. +- Insertion of coercions below product types refrains to unfold + constants (possible source of incompatibility). +- New support for fix/cofix in notations. + +Tactic Language + +- Second-order pattern-matching now working in Ltac "match" clauses + (syntax for second-order unification variable is "@?X"). +- Support for matching on let bindings in match context using syntax + "H := body" or "H := body : type". +- Ltac accepts integer arguments (syntax is "ltac:nnn" for nnn an integer). +- The general sequence tactical "expr_0 ; [ expr_1 | ... | expr_n ]" + is extended so that at most one expr_i may have the form "expr .." + or just "..". Also, n can be different from the number of subgoals + generated by expr_0. In this case, the value of expr (or idtac in + case of just "..") is applied to the intermediate subgoals to make + the number of tactics equal to the number of subgoals. +- A name used as the name of the parameter of a lemma (like f in + "apply f_equal with (f:=t)") is now interpreted as a ltac variable + if such a variable exists (this is a possible source of + incompatibility and it can be fixed by renaming the variables of a + ltac function into names that do not clash with the lemmas + parameter names used in the tactic). +- New syntax "Ltac tac ::= ..." to rebind a tactic to a new expression. +- "let rec ... in ... " now supported for expressions without explicit + parameters; interpretation is lazy to the contrary of "let ... in ..."; + hence, the "rec" keyword can be used to turn the argument of a + "let ... in ..." into a lazy one. +- Patterns for hypotheses types in "match goal" are now interpreted in + type_scope. +- A bound variable whose name is not used elsewhere now serves as + metavariable in "match" and it gets instantiated by an identifier + (allow e.g. to extract the name of a statement like "exists x, P x"). +- New printing of Ltac call trace for better debugging. + +Tactics + +- New tactics "apply -> term", "apply <- term", "apply -> term in + ident", "apply <- term in ident" for applying equivalences (iff). + +- Slight improvement of the hnf and simpl tactics when applied on + expressions with explicit occurrences of match or fix. + +- New tactics "eapply in", "erewrite", "erewrite in". + +- New tactics "ediscriminate", "einjection", "esimplify_eq". + +- Tactics "discriminate", "injection", "simplify_eq" now support any + term as argument. Clause "with" is also supported. + +- Unfoldable references can be given by notation's string rather than by name + in unfold. + +- The "with" arguments are now typed using informations from the current goal: + allows support for coercions and more inference of implicit arguments. + +- Application of "f_equal"-style lemmas works better. + +- Tactics elim, case, destruct and induction now support variants eelim, + ecase, edestruct and einduction. + +- Tactics destruct and induction now support the "with" option and the + "in" clause option. If the option "in" is used, an equality is added + to remember the term to which the induction or case analysis applied + (possible source of parsing incompatibilities when destruct or induction is + part of a let-in expression in Ltac; extra parentheses are then required). + +- New support for "as" clause in tactics "apply in" and "eapply in". + +- Some new intro patterns: + + * intro pattern "?A" genererates a fresh name based on A. + Caveat about a slight loss of compatibility: + Some intro patterns don't need space between them. In particular + intros ?a?b used to be legal and equivalent to intros ? a ? b. Now it + is still legal but equivalent to intros ?a ?b. + * intro pattern "(A & ... & Y & Z)" synonym to "(A,....,(Y,Z)))))" + for right-associative constructs like /\ or exists. + +- Several syntax extensions concerning "rewrite": + + * "rewrite A,B,C" can be used to rewrite A, then B, then C. These rewrites + occur only on the first subgoal: in particular, side-conditions of the + "rewrite A" are not concerned by the "rewrite B,C". + * "rewrite A by tac" allows to apply tac on all side-conditions generated by + the "rewrite A". + * "rewrite A at n" allows to select occurrences to rewrite: rewrite only + happen at the n-th exact occurrence of the first successful matching of + A in the goal. + * "rewrite 3 A" or "rewrite 3!A" is equivalent to "rewrite A,A,A". + * "rewrite !A" means rewriting A as long as possible (and at least once). + * "rewrite 3?A" means rewriting A at most three times. + * "rewrite ?A" means rewriting A as long as possible (possibly never). + * many of the above extensions can be combined with each other. + +- Introduction patterns better respect the structure of context in presence of + missing or extra names in nested disjunction-conjunction patterns [possible + source of rare incompatibilities]. + +- New syntax "rename a into b, c into d" for "rename a into b; rename c into d" + +- New tactics "dependent induction/destruction H [ generalizing id_1 .. id_n ]" + to do induction-inversion on instantiated inductive families à la BasicElim. + +- Tactics "apply" and "apply in" now able to reason modulo unfolding of + constants (possible source of incompatibility in situations where apply + may fail, e.g. as argument of a try or a repeat and in a ltac function); + versions that do not unfold are renamed into "simple apply" and + "simple apply in" (usable for compatibility or for automation). + +- Tactics "apply" and "apply in" now able to traverse conjunctions and to + select the first matching lemma among the components of the conjunction; + tactic "apply" also able to apply lemmas of conclusion an empty type. + +- Tactic "apply" now supports application of several lemmas in a row. + +- Tactics "set" and "pose" can set functions using notation "(f x1..xn := c)". + +- New tactic "instantiate" (without argument). + +- Tactic firstorder "with" and "using" options have their meaning swapped for + consistency with auto/eauto (source of incompatibility). + +- Tactic "generalize" now supports "at" options to specify occurrences + and "as" options to name the quantified hypotheses. + +- New tactic "specialize H with a" or "specialize (H a)" allows to transform + in-place a universally-quantified hypothesis (H : forall x, T x) into its + instantiated form (H : T a). Nota: "specialize" was in fact there in earlier + versions of Coq, but was undocumented, and had a slightly different behavior. + +- New tactic "contradict H" can be used to solve any kind of goal as long as + the user can provide afterwards a proof of the negation of the hypothesis H. + If H is already a negation, say ~T, then a proof of T is asked. + If the current goal is a negation, say ~U, then U is saved in H afterwards, + hence this new tactic "contradict" extends earlier tactic "swap", which is + now obsolete. + +- Tactics f_equal is now done in ML instead of Ltac: it now works on any + equality of functions, regardless of the arity of the function. + +- New options "before id", "at top", "at bottom" for tactics "move"/"intro". + +- Some more debug of reflexive omega (``romega``), and internal clarifications. + Moreover, romega now has a variant ``romega with *`` that can be also used + on non-Z goals (nat, N, positive) via a call to a translation tactic named + zify (its purpose is to Z-ify your goal...). This zify may also be used + independently of romega. + +- Tactic "remember" now supports an "in" clause to remember only selected + occurrences of a term. + +- Tactic "pose proof" supports name overwriting in case of specialization of an + hypothesis. + +- Semi-decision tactic "jp" for first-order intuitionistic logic moved to user + contributions (subsumed by "firstorder"). + +Program + +- Moved useful tactics in theories/Program and documented them. +- Add Program.Basics which contains standard definitions for functional + programming (id, apply, flip...) +- More robust obligation handling, dependent pattern-matching and + well-founded definitions. +- New syntax " dest term as pat in term " for destructing objects using + an irrefutable pattern while keeping equalities (use this instead of + "let" in Programs). +- Program CoFixpoint is accepted, Program Fixpoint uses the new way to infer + which argument decreases structurally. +- Program Lemma, Axiom etc... now permit to have obligations in the statement + iff they can be automatically solved by the default tactic. +- Renamed "Obligations Tactic" command to "Obligation Tactic". +- New command "Preterm [ of id ]" to see the actual term fed to Coq for + debugging purposes. +- New option "Transparent Obligations" to control the declaration of + obligations as transparent or opaque. All obligations are now transparent + by default, otherwise the system declares them opaque if possible. +- Changed the notations "left" and "right" to "in_left" and "in_right" to hide + the proofs in standard disjunctions, to avoid breaking existing scripts when + importing Program. Also, put them in program_scope. + +Type Classes + +- New "Class", "Instance" and "Program Instance" commands to define + classes and instances documented in the reference manual. +- New binding construct " [ Class_1 param_1 .. param_n, Class_2 ... ] " + for binding type classes, usable everywhere. +- New command " Print Classes " and " Print Instances some_class " to + print tables for typeclasses. +- New default eauto hint database "typeclass_instances" used by the default + typeclass instance search tactic. +- New theories directory "theories/Classes" for standard typeclasses + declarations. Module Classes.RelationClasses is a typeclass port of + Relation_Definitions plus a generic development of algebra on + n-ary heterogeneous predicates. + +Setoid rewriting + +- Complete (and still experimental) rewrite of the tactic + based on typeclasses. The old interface and semantics are + almost entirely respected, except: + + + Import Setoid is now mandatory to be able to call setoid_replace + and declare morphisms. + + + "-->", "++>" and "==>" are now right associative notations + declared at level 55 in scope signature_scope. + Their introduction may break existing scripts that defined + them as notations with different levels. + + + One needs to use [Typeclasses unfold [cst]] if [cst] is used + as an abbreviation hiding products in types of morphisms, + e.g. if ones redefines [relation] and declares morphisms + whose type mentions [relation]. + + + The [setoid_rewrite]'s semantics change when rewriting with + a lemma: it can rewrite two different instantiations of the lemma + at once. Use [setoid_rewrite H at 1] for (almost) the usual semantics. + [setoid_rewrite] will also try to rewrite under binders now, and can + succeed on different terms than before. In particular, it will unify under + let-bound variables. When called through [rewrite], the semantics are + unchanged though. + + + [Add Morphism term : id] has different semantics when used with + parametric morphism: it will try to find a relation on the parameters + too. The behavior has also changed with respect to default relations: + the most recently declared Setoid/Relation will be used, the documentation + explains how to customize this behavior. + + + Parametric Relation and Morphism are declared differently, using the + new [Add Parametric] commands, documented in the manual. + + + Setoid_Theory is now an alias to Equivalence, scripts building objects + of type Setoid_Theory need to unfold (or "red") the definitions + of Reflexive, Symmetric and Transitive in order to get the same goals + as before. Scripts which introduced variables explicitely will not break. + + + The order of subgoals when doing [setoid_rewrite] with side-conditions + is always the same: first the new goal, then the conditions. + +- New standard library modules ``Classes.Morphisms`` declares + standard morphisms on ``refl`` / ``sym`` / ``trans`` relations. + ``Classes.Morphisms_Prop`` declares morphisms on propositional + connectives and ``Classes.Morphisms_Relations`` on generalized predicate + connectives. ``Classes.Equivalence`` declares notations and tactics + related to equivalences and ``Classes.SetoidTactics`` defines the + setoid_replace tactics and some support for the ``Add *`` interface, + notably the tactic applied automatically before each ``Add Morphism`` + proof. + +- User-defined subrelations are supported, as well as higher-order morphisms + and rewriting under binders. The tactic is also extensible entirely in Ltac. + The documentation has been updated to cover these features. + +- [setoid_rewrite] and [rewrite] now support the [at] modifier to select + occurrences to rewrite, and both use the [setoid_rewrite] code, even when + rewriting with leibniz equality if occurrences are specified. + +Extraction + +- Improved behavior of the Caml extraction of modules: name clashes should + not happen anymore. + +- The command Extract Inductive has now a syntax for infix notations. This + allows in particular to map Coq lists and pairs onto Caml ones: + + + Extract Inductive list => list [ "[]" "(::)" ]. + + Extract Inductive prod => "(*)" [ "(,)" ]. + +- In pattern matchings, a default pattern "| _ -> ..." is now used whenever + possible if several branches are identical. For instance, functions + corresponding to decidability of equalities are now linear instead of + quadratic. + +- A new instruction Extraction Blacklist id1 .. idn allows to prevent filename + conflits with existing code, for instance when extracting module List + to Ocaml. + +CoqIDE + +- CoqIDE font defaults to monospace so as indentation to be meaningful. +- CoqIDE supports nested goals and any other kind of declaration in the middle + of a proof. +- Undoing non-tactic commands in CoqIDE works faster. +- New CoqIDE menu for activating display of various implicit informations. +- Added the possibility to choose the location of tabs in coqide: + (in Edit->Preferences->Misc) +- New Open and Save As dialogs in CoqIDE which filter ``*.v`` files. + +Tools + +- New stand-alone .vo files verifier "coqchk". +- Extended -I coqtop/coqc option to specify a logical dir: "-I dir -as coqdir". +- New coqtop/coqc option -exclude-dir to exclude subdirs for option -R. +- The binary "parser" has been renamed to "coq-parser". +- Improved coqdoc and dump of globalization information to give more + meta-information on identifiers. All categories of Coq definitions are + supported, which makes typesetting trivial in the generated documentation. + Support for hyperlinking and indexing developments in the tex output + has been implemented as well. + +Miscellaneous + +- Coq installation provides enough files so that Ocaml's extensions need not + the Coq sources to be compiled (this assumes O'Caml 3.10 and Camlp5). +- New commands "Set Whelp Server" and "Set Whelp Getter" to customize the + Whelp search tool. +- Syntax of "Test Printing Let ref" and "Test Printing If ref" changed into + "Test Printing Let for ref" and "Test Printing If for ref". +- An overhauled build system (new Makefiles); see dev/doc/build-system.txt. +- Add -browser option to configure script. +- Build a shared library for the C part of Coq, and use it by default on + non-(Windows or MacOS) systems. Bytecode executables are now pure. The + behaviour is configurable with -coqrunbyteflags, -coqtoolsbyteflags and + -custom configure options. +- Complexity tests can be skipped by setting the environment variable + COQTEST_SKIPCOMPLEXITY. + +Version 8.1 +----------- + +Summary of changes +~~~~~~~~~~~~~~~~~~ + +Coq version 8.1 adds various new functionalities. + +Benjamin Grégoire implemented an alternative algorithm to check the +convertibility of terms in the |Coq| type checker. This alternative +algorithm works by compilation to an efficient bytecode that is +interpreted in an abstract machine similar to Xavier Leroy’s ZINC +machine. Convertibility is performed by comparing the normal forms. This +alternative algorithm is specifically interesting for proofs by +reflection. More generally, it is convenient in case of intensive +computations. + +Christine Paulin implemented an extension of inductive types allowing +recursively non uniform parameters. Hugo Herbelin implemented +sort-polymorphism for inductive types (now called template polymorphism). + +Claudio Sacerdoti Coen improved the tactics for rewriting on arbitrary +compatible equivalence relations. He also generalized rewriting to +arbitrary transition systems. + +Claudio Sacerdoti Coen added new features to the module system. + +Benjamin Grégoire, Assia Mahboubi and Bruno Barras developed a new, more +efficient and more general simplification algorithm for rings and +semirings. + +Laurent Théry and Bruno Barras developed a new, significantly more +efficient simplification algorithm for fields. + +Hugo Herbelin, Pierre Letouzey, Julien Forest, Julien Narboux and +Claudio Sacerdoti Coen added new tactic features. + +Hugo Herbelin implemented matching on disjunctive patterns. + +New mechanisms made easier the communication between |Coq| and external +provers. Nicolas Ayache and Jean-Christophe Filliâtre implemented +connections with the provers cvcl, Simplify and zenon. Hugo Herbelin +implemented an experimental protocol for calling external tools from the +tactic language. + +Matthieu Sozeau developed Russell, an experimental language to specify +the behavior of programs with subtypes. + +A mechanism to automatically use some specific tactic to solve +unresolved implicit has been implemented by Hugo Herbelin. + +Laurent Théry’s contribution on strings and Pierre Letouzey and +Jean-Christophe Filliâtre’s contribution on finite maps have been +integrated to the |Coq| standard library. Pierre Letouzey developed a +library about finite sets “à la Objective Caml”. With Jean-Marc Notin, +he extended the library on lists. Pierre Letouzey’s contribution on +rational numbers has been integrated and extended. + +Pierre Corbineau extended his tactic for solving first-order statements. +He wrote a reflection-based intuitionistic tautology solver. + +Pierre Courtieu, Julien Forest and Yves Bertot added extra support to +reason on the inductive structure of recursively defined functions. + +Jean-Marc Notin significantly contributed to the general maintenance of +the system. He also took care of ``coqdoc``. + +Pierre Castéran contributed to the documentation of (co-)inductive types +and suggested improvements to the libraries. + +Pierre Corbineau implemented a declarative mathematical proof language, +usable in combination with the tactic-based style of proof. + +Finally, many users suggested improvements of the system through the +Coq-Club mailing list and bug-tracker systems, especially user groups +from INRIA Rocquencourt, Radboud University, University of Pennsylvania +and Yale University. + +| Palaiseau, July 2006 +| Hugo Herbelin +| + +Details of changes in 8.1beta +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Logic + +- Added sort-polymorphism on inductive families +- Allowance for recursively non uniform parameters in inductive types + +Syntax + +- No more support for version 7 syntax and for translation to version 8 syntax. +- In fixpoints, the { struct ... } annotation is not mandatory any more when + only one of the arguments has an inductive type +- Added disjunctive patterns in match-with patterns +- Support for primitive interpretation of string literals +- Extended support for Unicode ranges + +Vernacular commands + +- Added "Print Ltac qualid" to print a user defined tactic. +- Added "Print Rewrite HintDb" to print the content of a DB used by + autorewrite. +- Added "Print Canonical Projections". +- Added "Example" as synonym of "Definition". +- Added "Proposition" and "Corollary" as extra synonyms of "Lemma". +- New command "Whelp" to send requests to the Helm database of proofs + formalized in the Calculus of Inductive Constructions. +- Command "functional induction" has been re-implemented from the new + "Function" command. + +Ltac and tactic syntactic extensions + +- New primitive "external" for communication with tool external to Coq +- New semantics for "match t with": if a clause returns a + tactic, it is now applied to the current goal. If it fails, the next + clause or next matching subterm is tried (i.e. it behaves as "match + goal with" does). The keyword "lazymatch" can be used to delay the + evaluation of tactics occurring in matching clauses. +- Hint base names can be parametric in auto and trivial. +- Occurrence values can be parametric in unfold, pattern, etc. +- Added entry constr_may_eval for tactic extensions. +- Low-priority term printer made available in ML-written tactic extensions. +- "Tactic Notation" extended to allow notations of tacticals. + +Tactics + +- New implementation and generalization of ``setoid_*`` (``setoid_rewrite``, + ``setoid_symmetry``, ``setoid_transitivity``, ``setoid_reflexivity`` and ``autorewite``). + New syntax for declaring relations and morphisms (old syntax still working + with minor modifications, but deprecated). + +- New implementation (still experimental) of the ring tactic with a built-in + notion of coefficients and a better usage of setoids. + +- New conversion tactic "vm_compute": evaluates the goal (or an hypothesis) + with a call-by-value strategy, using the compiled version of terms. + +- When rewriting H where H is not directly a Coq equality, search first H for + a registered setoid equality before starting to reduce in H. This is unlikely + to break any script. Should this happen nonetheless, one can insert manually + some "unfold ... in H" before rewriting. + +- Fixed various bugs about (setoid) rewrite ... in ... (in particular bug #5941) + +- "rewrite ... in" now accepts a clause as place where to rewrite instead of + just a simple hypothesis name. For instance: + ``rewrite H in H1,H2 |- *`` means ``rewrite H in H1; rewrite H in H2; rewrite H`` + ``rewrite H in * |-`` will do try ``rewrite H in Hi`` for all hypothesis Hi <> H. + +- Added "dependent rewrite term" and "dependent rewrite term in hyp". + +- Added "autorewrite with ... in hyp [using ...]". + +- Tactic "replace" now accepts a "by" tactic clause. + +- Added "clear - id" to clear all hypotheses except the ones depending in id. + +- The argument of Declare Left Step and Declare Right Step is now a term + (it used to be a reference). + +- Omega now handles arbitrary precision integers. + +- Several bug fixes in Reflexive Omega (romega). + +- Idtac can now be left implicit in a [...|...] construct: for instance, + [ foo | | bar ] stands for [ foo | idtac | bar ]. + +- Fixed a "fold" bug (non critical but possible source of incompatibilities). + +- Added classical_left and classical_right which transforms ``|- A \/ B`` into + ``~B |- A`` and ``~A |- B`` respectively. + +- Added command "Declare Implicit Tactic" to set up a default tactic to be + used to solve unresolved subterms of term arguments of tactics. + +- Better support for coercions to Sortclass in tactics expecting type + arguments. + +- Tactic "assert" now accepts "as" intro patterns and "by" tactic clauses. + +- New tactic "pose proof" that generalizes "assert (id:=p)" with intro patterns. + +- New introduction pattern "?" for letting Coq choose a name. + +- Introduction patterns now support side hypotheses (e.g. intros [|] on + "(nat -> nat) -> nat" works). + +- New introduction patterns "->" and "<-" for immediate rewriting of + introduced hypotheses. + +- Introduction patterns coming after non trivial introduction patterns now + force full introduction of the first pattern (e.g. ``intros [[|] p]`` on + ``nat->nat->nat`` now behaves like ``intros [[|?] p]``) + +- Added "eassumption". + +- Added option 'using lemmas' to auto, trivial and eauto. + +- Tactic "congruence" is now complete for its intended scope (ground + equalities and inequalities with constructors). Furthermore, it + tries to equates goal and hypotheses. + +- New tactic "rtauto" solves pure propositional logic and gives a + reflective version of the available proof. + +- Numbering of "pattern", "unfold", "simpl", ... occurrences in "match + with" made consistent with the printing of the return clause after + the term to match in the "match-with" construct (use "Set Printing All" + to see hidden occurrences). + +- Generalization of induction "induction x1...xn using scheme" where + scheme is an induction principle with complex predicates (like the + ones generated by function induction). + +- Some small Ltac tactics has been added to the standard library + (file Tactics.v): + + * f_equal : instead of using the different f_equalX lemmas + * case_eq : a "case" without loss of information. An equality + stating the current situation is generated in every sub-cases. + * swap : for a negated goal ~B and a negated hypothesis H:~A, + swap H asks you to prove A from hypothesis B + * revert : revert H is generalize H; clear H. + +Extraction + +- All type parts should now disappear instead of sometimes producing _ + (for instance in Map.empty). +- Haskell extraction: types of functions are now printed, better + unsafeCoerce mechanism, both for hugs and ghc. +- Scheme extraction improved, see http://www.pps.jussieu.fr/~letouzey/scheme. +- Many bug fixes. + +Modules + +- Added "Locate Module qualid" to get the full path of a module. +- Module/Declare Module syntax made more uniform. +- Added syntactic sugar "Declare Module Export/Import" and + "Module Export/Import". +- Added syntactic sugar "Module M(Export/Import X Y: T)" and + "Module Type M(Export/Import X Y: T)" + (only for interactive definitions) +- Construct "with" generalized to module paths: + T with (Definition|Module) M1.M2....Mn.l := l'. + +Notations + +- Option "format" aware of recursive notations. +- Added insertion of spaces by default in recursive notations w/o separators. +- No more automatic printing box in case of user-provided printing "format". +- New notation "exists! x:A, P" for unique existence. +- Notations for specific numerals now compatible with generic notations of + numerals (e.g. "1" can be used to denote the unit of a group without + hiding 1%nat) + +Libraries + +- New library on String and Ascii characters (contributed by L. Thery). +- New library FSets+FMaps of finite sets and maps. +- New library QArith on rational numbers. +- Small extension of Zmin.V, new Zmax.v, new Zminmax.v. +- Reworking and extension of the files on classical logic and + description principles (possible incompatibilities) +- Few other improvements in ZArith potentially exceptionally breaking the + compatibility (useless hypothesys of Zgt_square_simpl and + Zlt_square_simpl removed; fixed names mentioning letter O instead of + digit 0; weaken premises in Z_lt_induction). +- Restructuration of Eqdep_dec.v and Eqdep.v: more lemmas in Type. +- Znumtheory now contains a gcd function that can compute within Coq. +- More lemmas stated on Type in Wf.v, removal of redundant Acc_iter and + Acc_iter2. +- Change of the internal names of lemmas in OmegaLemmas. +- Acc in Wf.v and clos_refl_trans in Relation_Operators.v now rely on + the allowance for recursively non uniform parameters (possible + source of incompatibilities: explicit pattern-matching on these + types may require to remove the occurrence associated to their + recursively non uniform parameter). +- Coq.List.In_dec has been set transparent (this may exceptionally break + proof scripts, set it locally opaque for compatibility). +- More on permutations of lists in List.v and Permutation.v. +- List.v has been much expanded. +- New file SetoidList.v now contains results about lists seen with + respect to a setoid equality. +- Library NArith has been expanded, mostly with results coming from + Intmap (for instance a bitwise xor), plus also a bridge between N and + Bitvector. +- Intmap has been reorganized. In particular its address type "addr" is + now N. User contributions known to use Intmap have been adapted + accordingly. If you're using this library please contact us. + A wrapper FMapIntMap now presents Intmap as a particular implementation + of FMaps. New developments are strongly encouraged to use either this + wrapper or any other implementations of FMap instead of using directly + this obsolete Intmap. + +Tools + +- New semantics for coqtop options ("-batch" expects option "-top dir" + for loading vernac file that contains definitions). +- Tool coq_makefile now removes custom targets that are file names in + "make clean" +- New environment variable COQREMOTEBROWSER to set the command invoked + to start the remote browser both in Coq and coqide. Standard syntax: + "%s" is the placeholder for the URL. + +Details of changes in 8.1gamma +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Syntax + +- changed parsing precedence of let/in and fun constructions of Ltac: + let x := t in e1; e2 is now parsed as let x := t in (e1;e2). + +Language and commands + +- Added sort-polymorphism for definitions in Type (but finally abandonned). +- Support for implicit arguments in the types of parameters in + (co-)fixpoints and (co-)inductive declarations. +- Improved type inference: use as much of possible general information. + before applying irreversible unification heuristics (allow e.g. to + infer the predicate in "(exist _ 0 (refl_equal 0) : {n:nat | n=0 })"). +- Support for Miller-Pfenning's patterns unification in type synthesis + (e.g. can infer P such that P x y = phi(x,y)). +- Support for "where" clause in cofixpoint definitions. +- New option "Set Printing Universes" for making Type levels explicit. + +Tactics + +- Improved implementation of the ring and field tactics. For compatibility + reasons, the previous tactics are renamed as legacy ring and legacy field, + but should be considered as deprecated. +- New declarative mathematical proof language. +- Support for argument lists of arbitrary length in Tactic Notation. +- ``rewrite ... in H`` now fails if ``H`` is used either in an hypothesis + or in the goal. +- The semantics of ``rewrite ... in *`` has been slightly modified (see doc). +- Support for ``as`` clause in tactic injection. +- New forward-reasoning tactic "apply in". +- Ltac fresh operator now builds names from a concatenation of its arguments. +- New ltac tactic "remember" to abstract over a subterm and keep an equality +- Support for Miller-Pfenning's patterns unification in apply/rewrite/... + (may lead to few incompatibilities - generally now useless tactic calls). + +Bug fixes + +- Fix for notations involving basic "match" expressions. +- Numerous other bugs solved (a few fixes may lead to incompatibilities). + +Details of changes in 8.1 +~~~~~~~~~~~~~~~~~~~~~~~~~ + +Bug fixes + +- Many bugs have been fixed (cf coq-bugs web page) + +Tactics + +- New tactics ring, ring_simplify and new tactic field now able to manage + power to a positive integer constant. Tactic ring on Z and R, and + field on R manage power (may lead to incompatibilities with V8.1gamma). +- Tactic field_simplify now applicable in hypotheses. +- New field_simplify_eq for simplifying field equations into ring equations. +- Tactics ring, ring_simplify, field, field_simplify and field_simplify_eq + all able to apply user-given equations to rewrite monoms on the fly + (see documentation). + +Libraries + +- New file ConstructiveEpsilon.v defining an epsilon operator and + proving the axiom of choice constructively for a countable domain + and a decidable predicate. + +Version 8.0 +----------- + +Summary of changes +~~~~~~~~~~~~~~~~~~ + +Coq version 8 is a major revision of the |Coq| proof assistant. First, the +underlying logic is slightly different. The so-called *impredicativity* +of the sort Set has been dropped. The main reason is that it is +inconsistent with the principle of description which is quite a useful +principle for formalizing mathematics within classical logic. Moreover, +even in an constructive setting, the impredicativity of Set does not add +so much in practice and is even subject of criticism from a large part +of the intuitionistic mathematician community. Nevertheless, the +impredicativity of Set remains optional for users interested in +investigating mathematical developments which rely on it. + +Secondly, the concrete syntax of terms has been completely revised. The +main motivations were + +- a more uniform, purified style: all constructions are now lowercase, + with a functional programming perfume (e.g. abstraction is now + written fun), and more directly accessible to the novice (e.g. + dependent product is now written forall and allows omission of + types). Also, parentheses are no longer mandatory for function + application. + +- extensibility: some standard notations (e.g. “<” and “>”) were + incompatible with the previous syntax. Now all standard arithmetic + notations (=, +, \*, /, <, <=, ... and more) are directly part of the + syntax. + +Together with the revision of the concrete syntax, a new mechanism of +*interpretation scopes* permits to reuse the same symbols (typically +, +-, \*, /, <, <=) in various mathematical theories without any +ambiguities for |Coq|, leading to a largely improved readability of |Coq| +scripts. New commands to easily add new symbols are also provided. + +Coming with the new syntax of terms, a slight reform of the tactic +language and of the language of commands has been carried out. The +purpose here is a better uniformity making the tactics and commands +easier to use and to remember. + +Thirdly, a restructuring and uniformization of the standard library of +Coq has been performed. There is now just one Leibniz equality usable +for all the different kinds of |Coq| objects. Also, the set of real +numbers now lies at the same level as the sets of natural and integer +numbers. Finally, the names of the standard properties of numbers now +follow a standard pattern and the symbolic notations for the standard +definitions as well. + +The fourth point is the release of |CoqIDE|, a new graphical gtk2-based +interface fully integrated with |Coq|. Close in style to the Proof General +Emacs interface, it is faster and its integration with |Coq| makes +interactive developments more friendly. All mathematical Unicode symbols +are usable within |CoqIDE|. + +Finally, the module system of |Coq| completes the picture of |Coq| version +8.0. Though released with an experimental status in the previous version +7.4, it should be considered as a salient feature of the new version. + +Besides, |Coq| comes with its load of novelties and improvements: new or +improved tactics (including a new tactic for solving first-order +statements), new management commands, extended libraries. + +Bruno Barras and Hugo Herbelin have been the main contributors of the +reflection and the implementation of the new syntax. The smart automatic +translator from old to new syntax released with |Coq| is also their work +with contributions by Olivier Desmettre. + +Hugo Herbelin is the main designer and implementer of the notion of +interpretation scopes and of the commands for easily adding new +notations. + +Hugo Herbelin is the main implementer of the restructured standard library. + +Pierre Corbineau is the main designer and implementer of the new tactic +for solving first-order statements in presence of inductive types. He is +also the maintainer of the non-domain specific automation tactics. + +Benjamin Monate is the developer of the |CoqIDE| graphical interface with +contributions by Jean-Christophe Filliâtre, Pierre Letouzey, Claude +Marché and Bruno Barras. + +Claude Marché coordinated the edition of the Reference Manual for |Coq| +V8.0. + +Pierre Letouzey and Jacek Chrząszcz respectively maintained the +extraction tool and module system of |Coq|. + +Jean-Christophe Filliâtre, Pierre Letouzey, Hugo Herbelin and other +contributors from Sophia-Antipolis and Nijmegen participated in +extending the library. + +Julien Narboux built a NSIS-based automatic |Coq| installation tool for +the Windows platform. + +Hugo Herbelin and Christine Paulin coordinated the development which was +under the responsibility of Christine Paulin. + +| Palaiseau & Orsay, Apr. 2004 +| Hugo Herbelin & Christine Paulin +| (updated Apr. 2006) +| + +Details of changes in 8.0beta old syntax +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Logic + +- Set now predicative by default +- New option -impredicative-set to set Set impredicative +- The standard library doesn't need impredicativity of Set and is + compatible with the classical axioms which contradict Set impredicativity + +Syntax for arithmetic + +- Notation "=" and "<>" in Z and R are no longer implicitly in Z or R + (with possible introduction of a coercion), use <Z>...=... or + <Z>...<>... instead +- Locate applied to a simple string (e.g. "+") searches for all + notations containing this string + +Vernacular commands + +- "Declare ML Module" now allows to import .cma files. This avoids to use a + bunch of "Declare ML Module" statements when using several ML files. +- "Set Printing Width n" added, allows to change the size of width printing. +- "Implicit Variables Type x,y:t" (new syntax: "Implicit Types x y:t") + assigns default types for binding variables. +- Declarations of Hints and Notation now accept a "Local" flag not to + be exported outside the current file even if not in section +- "Print Scopes" prints all notations +- New command "About name" for light printing of type, implicit arguments, etc. +- New command "Admitted" to declare incompletely proven statement as axioms +- New keyword "Conjecture" to declare an axiom intended to be provable +- SearchAbout can now search for lemmas referring to more than one constant + and on substrings of the name of the lemma +- "Print Implicit" displays the implicit arguments of a constant +- Locate now searches for all names having a given suffix +- New command "Functional Scheme" for building an induction principle + from a function defined by case analysis and fix. + +Commands + +- new coqtop/coqc option -dont-load-proofs not to load opaque proofs in memory + +Implicit arguments + +- Inductive in sections declared with implicits now "discharged" with + implicits (like constants and variables) +- Implicit Arguments flags are now synchronous with reset +- New switch "Unset/Set Printing Implicits" (new syntax: "Unset/Set Printing + Implicit") to globally control printing of implicits + +Grammar extensions + +- Many newly supported UTF-8 encoded unicode blocks + - Greek letters (0380-03FF), Hebrew letters (U05D0-05EF), letter-like + symbols (2100-214F, that includes double N,Z,Q,R), prime + signs (from 2080-2089) and characters from many written languages + are valid in identifiers + - mathematical operators (2200-22FF), supplemental mathematical + operators (2A00-2AFF), miscellaneous technical (2300-23FF that + includes sqrt symbol), miscellaneous symbols (2600-26FF), arrows + (2190-21FF and 2900-297F), invisible mathematical operators (from + 2080-2089), ... are valid symbols + +Library + +- New file about the factorial function in Arith + +- An additional elimination Acc_iter for Acc, simplier than Acc_rect. + This new elimination principle is used for definition well_founded_induction. + +- New library NArith on binary natural numbers + +- R is now of type Set + +- Restructuration in ZArith library + + + "true_sub" used in Zplus now a definition, not a local one (source + of incompatibilities in proof referring to true_sub, may need extra Unfold) + + Some lemmas about minus moved from fast_integer to Arith/Minus.v + (le_minus, lt_mult_left) (theoretical source of incompatibilities) + + Several lemmas moved from auxiliary.v and zarith_aux.v to + fast_integer.v (theoretical source of incompatibilities) + + Variables names of iff_trans changed (source of incompatibilities) + + ZArith lemmas named ``OMEGA`` something or ``fast_`` something, and lemma ``new_var`` + are now out of ZArith (except ``OMEGA2``) + + Redundant ZArith lemmas have been renamed: for the following pairs, + use the second name (Zle_Zmult_right2, Zle_mult_simpl), (OMEGA2, + Zle_0_plus), (Zplus_assoc_l, Zplus_assoc), (Zmult_one, Zmult_1_n), + (Zmult_assoc_l, Zmult_assoc), (Zmult_minus_distr, Zmult_Zminus_distr_l) + (add_un_double_moins_un_xO, is_double_moins_un), + (Rlt_monotony_rev,Rlt_monotony_contra) (source of incompatibilities) + +- Few minor changes (no more implicit arguments in + Zmult_Zminus_distr_l and Zmult_Zminus_distr_r, lemmas moved from + Zcomplements to other files) (rare source of incompatibilities) + +- New lemmas provided by users added + +Tactic language + +- Fail tactic now accepts a failure message +- Idtac tactic now accepts a message +- New primitive tactic "FreshId" (new syntax: "fresh") to generate new names +- Debugger prints levels of calls + +Tactics + +- Replace can now replace proofs also +- Fail levels are now decremented at "Match Context" blocks only and + if the right-hand-side of "Match term With" are tactics, these + tactics are never evaluated immediately and do not induce + backtracking (in contrast with "Match Context") +- Quantified names now avoid global names of the current module (like + Intro names did) [source of rare incompatibilities: 2 changes in the set of + user contribs] +- NewDestruct/NewInduction accepts intro patterns as introduction names +- NewDestruct/NewInduction now work for non-inductive type using option "using" +- A NewInduction naming bug for inductive types with functional + arguments (e.g. the accessibility predicate) has been fixed (source + of incompatibilities) +- Symmetry now applies to hypotheses too +- Inversion now accept option "as [ ... ]" to name the hypotheses +- Contradiction now looks also for contradictory hypotheses stating ~A and A + (source of incompatibility) +- "Contradiction c" try to find an hypothesis in context which + contradicts the type of c +- Ring applies to new library NArith (require file NArithRing) +- Field now works on types in Set +- Auto with reals now try to replace le by ge (Rge_le is no longer an + immediate hint), resulting in shorter proofs +- Instantiate now works in hyps (syntax : Instantiate in ...) +- Some new tactics : EConstructor, ELeft, Eright, ESplit, EExists +- New tactic "functional induction" to perform case analysis and + induction following the definition of a function. +- Clear now fails when trying to remove a local definition used by + a constant appearing in the current goal + +Extraction (See details in plugins/extraction/CHANGES) + +- The old commands: (Recursive) Extraction Module M. + are now: (Recursive) Extraction Library M. + To use these commands, M should come from a library M.v +- The other syntax Extraction & Recursive Extraction now accept + module names as arguments. + +Bugs + +- see coq-bugs server for the complete list of fixed bugs + +Miscellaneous + +- Implicit parameters of inductive types definition now taken into + account for infering other implicit arguments + +Incompatibilities + +- Persistence of true_sub (4 incompatibilities in Coq user contributions) +- Variable names of some constants changed for a better uniformity (2 changes + in Coq user contributions) +- Naming of quantified names in goal now avoid global names (2 occurrences) +- NewInduction naming for inductive types with functional arguments + (no incompatibility in Coq user contributions) +- Contradiction now solve more goals (source of 2 incompatibilities) +- Merge of eq and eqT may exceptionally result in subgoals now + solved automatically +- Redundant pairs of ZArith lemmas may have different names: it may + cause "Apply/Rewrite with" to fail if using the first name of a pair + of redundant lemmas (this is solved by renaming the variables bound by + "with"; 3 incompatibilities in Coq user contribs) +- ML programs referring to constants from fast_integer.v must use + "Coqlib.gen_constant_modules Coqlib.zarith_base_modules" instead + +Details of changes in 8.0beta new syntax +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +New concrete syntax + +- A completely new syntax for terms +- A more uniform syntax for tactics and the tactic language +- A few syntactic changes for vernacular commands +- A smart automatic translator translating V8.0 files in old syntax to + files valid for V8.0 + +Syntax extensions + +- "Grammar" for terms disappears +- "Grammar" for tactics becomes "Tactic Notation" +- "Syntax" disappears +- Introduction of a notion of interpretation scope allowing to use the + same notations in various contexts without using specific delimiters + (e.g the same expression "4<=3+x" is interpreted either in "nat", + "positive", "N" (previously "entier"), "Z", "R", depending on which + interpretation scope is currently open) [see documentation for details] +- Notation now mandatorily requires a precedence and associativity + (default was to set precedence to 1 and associativity to none) + +Revision of the standard library + +- Many lemmas and definitions names have been made more uniform mostly + in Arith, NArith, ZArith and Reals (e.g : "times" -> "Pmult", + "times_sym" -> "Pmult_comm", "Zle_Zmult_pos_right" -> + "Zmult_le_compat_r", "SUPERIEUR" -> "Gt", "ZERO" -> "Z0") +- Order and names of arguments of basic lemmas on nat, Z, positive and R + have been made uniform. +- Notions of Coq initial state are declared with (strict) implicit arguments +- eq merged with eqT: old eq disappear, new eq (written =) is old eqT + and new eqT is syntactic sugar for new eq (notation == is an alias + for = and is written as it, exceptional source of incompatibilities) +- Similarly, ex, ex2, all, identity are merged with exT, exT2, allT, identityT +- Arithmetical notations for nat, positive, N, Z, R, without needing + any backquote or double-backquotes delimiters. +- In Lists: new concrete notations; argument of nil is now implicit +- All changes in the library are taken in charge by the translator + +Semantical changes during translation + +- Recursive keyword set by default (and no longer needed) in Tactic Definition +- Set Implicit Arguments is strict by default in new syntax +- reductions in hypotheses of the form "... in H" now apply to the type + also if H is a local definition +- etc + +Gallina + +- New syntax of the form "Inductive bool : Set := true, false : bool." for + enumerated types +- Experimental syntax of the form p.(fst) for record projections + (activable with option "Set Printing Projections" which is + recognized by the translator) + +Known problems of the automatic translation + +- iso-latin-1 characters are no longer supported: move your files to + 7-bits ASCII or unicode before translation (swith to unicode is + automatically done if a file is loaded and saved again by coqide) +- Renaming in ZArith: incompatibilities in Coq user contribs due to + merging names INZ, from Reals, and inject_nat. +- Renaming and new lemmas in ZArith: may clash with names used by users +- Restructuration of ZArith: replace requirement of specific modules + in ZArith by "Require Import ZArith_base" or "Require Import ZArith" +- Some implicit arguments must be made explicit before translation: typically + for "length nil", the implicit argument of length must be made explicit +- Grammar rules, Infix notations and V7.4 Notations must be updated wrt the + new scheme for syntactic extensions (see translator documentation) +- Unsafe for annotation Cases when constructors coercions are used or when + annotations are eta-reduced predicates + +Details of changes in 8.0 +~~~~~~~~~~~~~~~~~~~~~~~~~ + +Vernacular commands + +- New option "Set Printing All" to deactivate all high-level forms of + printing (implicit arguments, coercions, destructing let, + if-then-else, notations, projections) +- "Functional Scheme" and "Functional Induction" extended to polymorphic + types and dependent types +- Notation now allows recursive patterns, hence recovering parts of the + fonctionalities of pre-V8 Grammar/Syntax commands +- Command "Print." discontinued. +- Redundant syntax "Implicit Arguments On/Off" discontinued + +New syntax + +- Semantics change of the if-then-else construction in new syntax: + "if c then t1 else t2" now stands for + "match c with c1 _ ... _ => t1 | c2 _ ... _ => t2 end" + with no dependency of t1 and t2 in the arguments of the constructors; + this may cause incompatibilities for files translated using coq 8.0beta + +Interpretation scopes + +- Delimiting key %bool for bool_scope added +- Import no more needed to activate argument scopes from a module + +Tactics and the tactic Language + +- Semantics of "assert" is now consistent with the reference manual +- New tactics stepl and stepr for chaining transitivity steps +- Tactic "replace ... with ... in" added +- Intro patterns now supported in Ltac (parsed with prefix "ipattern:") + +Executables and tools + +- Added option -top to change the name of the toplevel module "Top" +- Coqdoc updated to new syntax and now part of Coq sources +- XML exportation tool now exports the structure of vernacular files + (cf chapter 13 in the reference manual) + +User contributions + +- User contributions have been updated to the new syntax + +Bug fixes + +- Many bugs have been fixed (cf coq-bugs web page) diff --git a/doc/sphinx/conf.py b/doc/sphinx/conf.py new file mode 100755 index 0000000000..48ad60c6dd --- /dev/null +++ b/doc/sphinx/conf.py @@ -0,0 +1,459 @@ +#!/usr/bin/env python3 +# -*- coding: utf-8 -*- +########################################################################## +## # The Coq Proof Assistant / The Coq Development Team ## +## v # INRIA, CNRS and contributors - Copyright 1999-2018 ## +## <O___,, # (see CREDITS file for the list of authors) ## +## \VV/ ############################################################### +## // # This file is distributed under the terms of the ## +## # GNU Lesser General Public License Version 2.1 ## +## # (see LICENSE file for the text of the license) ## +########################################################################## +# +# Coq documentation build configuration file, created by +# sphinx-quickstart on Wed May 11 11:23:13 2016. +# +# This file is execfile()d with the current directory set to its +# containing dir. +# +# Note that not all possible configuration values are present in this +# autogenerated file. +# +# All configuration values have a default; values that are commented out +# serve to show the default. + +import sys +import os +from shutil import copyfile +import sphinx + +# Increase recursion limit for sphinx +sys.setrecursionlimit(3000) + +# If extensions (or modules to document with autodoc) are in another directory, +# add these directories to sys.path here. If the directory is relative to the +# documentation root, use os.path.abspath to make it absolute, like shown here. +sys.path.append(os.path.abspath('../tools/')) +sys.path.append(os.path.abspath('../../config/')) + +import coq_config + +# -- Prolog --------------------------------------------------------------- + +# Include substitution definitions in all files +with open("refman-preamble.rst") as s: + rst_prolog = s.read() + +# -- General configuration ------------------------------------------------ + +# If your documentation needs a minimal Sphinx version, state it here. +#needs_sphinx = '1.0' + +# Add any Sphinx extension module names here, as strings. They can be +# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom +# ones. +extensions = [ + 'sphinx.ext.mathjax', + 'sphinx.ext.todo', + 'sphinxcontrib.bibtex', + 'coqrst.coqdomain' +] + +# Change this to "info" or "warning" to get notifications about undocumented Coq +# objects (objects with no contents). +report_undocumented_coq_objects = "warning" + +# Add any paths that contain templates here, relative to this directory. +templates_path = ['_templates'] + +# The suffix(es) of source filenames. +# You can specify multiple suffix as a list of string: +# source_suffix = ['.rst', '.md'] +source_suffix = '.rst' + +# The encoding of source files. +#source_encoding = 'utf-8-sig' + +# Add extra cases here to support more formats + +SUPPORTED_FORMATS = ["html", "latex"] + +def readbin(fname): + try: + with open(fname, mode="rb") as f: + return f.read() + except FileNotFoundError: + return None + +def copy_formatspecific_files(app): + ext = ".{}.rst".format(app.builder.name) + for fname in sorted(os.listdir(app.srcdir)): + if fname.endswith(ext): + src = os.path.join(app.srcdir, fname) + dst = os.path.join(app.srcdir, fname[:-len(ext)] + ".rst") + logger = sphinx.util.logging.getLogger(__name__) + if readbin(src) == readbin(dst): + logger.info("Skipping {}: {} is up to date".format(src, dst)) + else: + logger.info("Copying {} to {}".format(src, dst)) + copyfile(src, dst) + +def setup(app): + app.connect('builder-inited', copy_formatspecific_files) + +# The master toctree document. +# We create this file in `copy_master_doc` above. +master_doc = "index" + +# General information about the project. +project = 'Coq' +copyright = '1999-2018, Inria' +author = 'The Coq Development Team' + +# The version info for the project you're documenting, acts as replacement for +# |version| and |release|, also used in various other places throughout the +# built documents. +# +# The short X.Y version. +version = coq_config.version +# The full version, including alpha/beta/rc tags. +release = coq_config.version + +# The language for content autogenerated by Sphinx. Refer to documentation +# for a list of supported languages. +# +# This is also used if you do content translation via gettext catalogs. +# Usually you set "language" from the command line for these cases. +language = None + +# There are two options for replacing |today|: either, you set today to some +# non-false value, then it is used: +#today = '' +# Else, today_fmt is used as the format for a strftime call. +#today_fmt = '%B %d, %Y' + +# List of patterns, relative to source directory, that match files and +# directories to ignore when looking for source files. +# This patterns also effect to html_static_path and html_extra_path +exclude_patterns = [ + '_build', + 'Thumbs.db', + '.DS_Store', + 'introduction.rst', + 'refman-preamble.rst', + 'README.rst', + 'README.gen.rst', + 'README.template.rst' +] + ["*.{}.rst".format(fmt) for fmt in SUPPORTED_FORMATS] + +# The reST default role (used for this markup: `text`) to use for all +# documents. +default_role = 'literal' + +# Use the Coq domain +primary_domain = 'coq' + +# If true, '()' will be appended to :func: etc. cross-reference text. +#add_function_parentheses = True + +# If true, the current module name will be prepended to all description +# unit titles (such as .. function::). +#add_module_names = True + +# If true, sectionauthor and moduleauthor directives will be shown in the +# output. They are ignored by default. +#show_authors = False + +# The name of the Pygments (syntax highlighting) style to use. +pygments_style = 'sphinx' +highlight_language = 'text' +suppress_warnings = ["misc.highlighting_failure"] + +# A list of ignored prefixes for module index sorting. +#modindex_common_prefix = [] + +# If true, keep warnings as "system message" paragraphs in the built documents. +#keep_warnings = False + +# If true, `todo` and `todoList` produce output, else they produce nothing. +todo_include_todos = False + +# Extra warnings, including undefined references +nitpicky = False + +# -- Options for HTML output ---------------------------------------------- + +# The theme to use for HTML and HTML Help pages. See the documentation for +# a list of builtin themes. +html_theme = 'sphinx_rtd_theme' +# html_theme = 'agogo' +# html_theme = 'alabaster' +# html_theme = 'haiku' +# html_theme = 'bizstyle' + +# Theme options are theme-specific and customize the look and feel of a theme +# further. For a list of options available for each theme, see the +# documentation. +html_theme_options = { + 'collapse_navigation': False +} +html_context = { + 'display_github': True, + 'github_user': 'coq', + 'github_repo': 'coq', + 'github_version': 'master', + 'conf_py_path': '/doc/sphinx/' +} + +# Add any paths that contain custom themes here, relative to this directory. +import sphinx_rtd_theme +html_theme_path = [sphinx_rtd_theme.get_html_theme_path()] + +# The name for this set of Sphinx documents. +# "<project> v<release> documentation" by default. +#html_title = 'Coq 8.5 v8.5pl1' + +# A shorter title for the navigation bar. Default is the same as html_title. +#html_short_title = None + +# The name of an image file (relative to this directory) to place at the top +# of the sidebar. +#html_logo = None + +# The name of an image file (relative to this directory) to use as a favicon of +# the docs. This file should be a Windows icon file (.ico) being 16x16 or 32x32 +# pixels large. +#html_favicon = None + +# Add any paths that contain custom static files (such as style sheets) here, +# relative to this directory. They are copied after the builtin static files, +# so a file named "default.css" will overwrite the builtin "default.css". +html_static_path = ['_static'] + +# Add any extra paths that contain custom files (such as robots.txt or +# .htaccess) here, relative to this directory. These files are copied +# directly to the root of the documentation. +#html_extra_path = [] + +# If not None, a 'Last updated on:' timestamp is inserted at every page +# bottom, using the given strftime format. +# The empty string is equivalent to '%b %d, %Y'. +#html_last_updated_fmt = None + +# FIXME: this could be re-enabled after ensuring that smart quotes are locally +# disabled for all relevant directives +smartquotes = False + +# Custom sidebar templates, maps document names to template names. +#html_sidebars = {} + +# Additional templates that should be rendered to pages, maps page names to +# template names. +#html_additional_pages = {} + +# If false, no module index is generated. +#html_domain_indices = True + +# If false, no index is generated. +#html_use_index = True + +# If true, the index is split into individual pages for each letter. +#html_split_index = False + +# If true, links to the reST sources are added to the pages. +#html_show_sourcelink = True + +# If true, "Created using Sphinx" is shown in the HTML footer. Default is True. +#html_show_sphinx = True + +# If true, "(C) Copyright ..." is shown in the HTML footer. Default is True. +#html_show_copyright = True + +# If true, an OpenSearch description file will be output, and all pages will +# contain a <link> tag referring to it. The value of this option must be the +# base URL from which the finished HTML is served. +#html_use_opensearch = '' + +# This is the file name suffix for HTML files (e.g. ".xhtml"). +#html_file_suffix = None + +# Language to be used for generating the HTML full-text search index. +# Sphinx supports the following languages: +# 'da', 'de', 'en', 'es', 'fi', 'fr', 'h', 'it', 'ja' +# 'nl', 'no', 'pt', 'ro', 'r', 'sv', 'tr', 'zh' +#html_search_language = 'en' + +# A dictionary with options for the search language support, empty by default. +# 'ja' uses this config value. +# 'zh' user can custom change `jieba` dictionary path. +#html_search_options = {'type': 'default'} + +# The name of a javascript file (relative to the configuration directory) that +# implements a search results scorer. If empty, the default will be used. +#html_search_scorer = 'scorer.js' + +# -- Options for LaTeX output --------------------------------------------- + +########################### +# Set things up for XeTeX # +########################### + +latex_elements = { + 'babel': '', + 'fontenc': '', + 'inputenc': '', + 'utf8extra': '', + 'cmappkg': '', + 'papersize': 'letterpaper', + 'classoptions': ',openany', # No blank pages + 'polyglossia': '\\usepackage{polyglossia}', + 'sphinxsetup': 'verbatimwithframe=false', + 'preamble': r""" + \usepackage{unicode-math} + \usepackage{microtype} + + % Macro definitions + \usepackage{refman-preamble} + + % Style definitions for notations + \usepackage{coqnotations} + + % Style tweaks + \newcssclass{sigannot}{\textrm{#1:}} + + % Silence 'LaTeX Warning: Command \nobreakspace invalid in math mode' + \everymath{\def\nobreakspace{\ }} + """ +} + +latex_engine = "xelatex" + +######## +# done # +######## + +latex_additional_files = [ + "refman-preamble.sty", + "_static/coqnotations.sty" +] + +latex_documents = [('index', 'CoqRefMan.tex', 'The Coq Reference Manual', author, 'manual')] + +# The name of an image file (relative to this directory) to place at the top of +# the title page. +# latex_logo = "../../ide/coq.png" + +# If true, show page references after internal links. +#latex_show_pagerefs = False + +# If true, show URL addresses after external links. +latex_show_urls = 'footnote' + +# -- Options for manual page output --------------------------------------- + +# One entry per manual page. List of tuples +# (source start file, name, description, authors, manual section). +#man_pages = [ +# (master_doc, 'coq', 'Coq Documentation', +# [author], 1) +#] + +# If true, show URL addresses after external links. +#man_show_urls = False + + +# -- Options for Texinfo output ------------------------------------------- + +# Grouping the document tree into Texinfo files. List of tuples +# (source start file, target name, title, author, +# dir menu entry, description, category) +#texinfo_documents = [ +# (master_doc, 'Coq', 'Coq Documentation', +# author, 'Coq', 'One line description of project.', +# 'Miscellaneous'), +#] + +# Documents to append as an appendix to all manuals. +#texinfo_appendices = [] + +# If false, no module index is generated. +#texinfo_domain_indices = True + +# How to display URL addresses: 'footnote', 'no', or 'inline'. +#texinfo_show_urls = 'footnote' + +# If true, do not generate a @detailmenu in the "Top" node's menu. +#texinfo_no_detailmenu = False + + +# -- Options for Epub output ---------------------------------------------- + +# Bibliographic Dublin Core info. +#epub_title = project +#epub_author = author +#epub_publisher = author +#epub_copyright = copyright + +# The basename for the epub file. It defaults to the project name. +#epub_basename = project + +# The HTML theme for the epub output. Since the default themes are not +# optimized for small screen space, using the same theme for HTML and epub +# output is usually not wise. This defaults to 'epub', a theme designed to save +# visual space. +#epub_theme = 'epub' + +# The language of the text. It defaults to the language option +# or 'en' if the language is not set. +#epub_language = '' + +# The scheme of the identifier. Typical schemes are ISBN or URL. +#epub_scheme = '' + +# The unique identifier of the text. This can be a ISBN number +# or the project homepage. +#epub_identifier = '' + +# A unique identification for the text. +#epub_uid = '' + +# A tuple containing the cover image and cover page html template filenames. +#epub_cover = () + +# A sequence of (type, uri, title) tuples for the guide element of content.opf. +#epub_guide = () + +# HTML files that should be inserted before the pages created by sphinx. +# The format is a list of tuples containing the path and title. +#epub_pre_files = [] + +# HTML files that should be inserted after the pages created by sphinx. +# The format is a list of tuples containing the path and title. +#epub_post_files = [] + +# A list of files that should not be packed into the epub file. +epub_exclude_files = ['search.html'] + +# The depth of the table of contents in toc.ncx. +#epub_tocdepth = 3 + +# Allow duplicate toc entries. +#epub_tocdup = True + +# Choose between 'default' and 'includehidden'. +#epub_tocscope = 'default' + +# Fix unsupported image types using the Pillow. +#epub_fix_images = False + +# Scale large images. +#epub_max_image_width = 0 + +# How to display URL addresses: 'footnote', 'no', or 'inline'. +#epub_show_urls = 'inline' + +# If false, no index is generated. +#epub_use_index = True + +# navtree options +navtree_shift = True diff --git a/doc/sphinx/coq-cmdindex.rst b/doc/sphinx/coq-cmdindex.rst new file mode 100644 index 0000000000..fd0b342ae4 --- /dev/null +++ b/doc/sphinx/coq-cmdindex.rst @@ -0,0 +1,7 @@ +:orphan: + +.. hack to get index in TOC + +----------------- +Command index +----------------- diff --git a/doc/sphinx/coq-exnindex.rst b/doc/sphinx/coq-exnindex.rst new file mode 100644 index 0000000000..fc55e91eee --- /dev/null +++ b/doc/sphinx/coq-exnindex.rst @@ -0,0 +1,7 @@ +:orphan: + +.. hack to get index in TOC + +------------------------- +Errors and warnings index +------------------------- diff --git a/doc/sphinx/coq-optindex.rst b/doc/sphinx/coq-optindex.rst new file mode 100644 index 0000000000..0961bea61f --- /dev/null +++ b/doc/sphinx/coq-optindex.rst @@ -0,0 +1,7 @@ +:orphan: + +.. hack to get index in TOC + +------------------------------- +Flags, options and tables index +------------------------------- diff --git a/doc/sphinx/coq-tacindex.rst b/doc/sphinx/coq-tacindex.rst new file mode 100644 index 0000000000..31b2f7f8cb --- /dev/null +++ b/doc/sphinx/coq-tacindex.rst @@ -0,0 +1,7 @@ +:orphan: + +.. hack to get index in TOC + +------------- +Tactic index +------------- diff --git a/doc/sphinx/coqdoc.css b/doc/sphinx/coqdoc.css new file mode 100644 index 0000000000..a34bb81ebd --- /dev/null +++ b/doc/sphinx/coqdoc.css @@ -0,0 +1,338 @@ +/************************************************************************/ +/* * The Coq Proof Assistant / The Coq Development Team */ +/* v * INRIA, CNRS and contributors - Copyright 1999-2018 */ +/* <O___,, * (see CREDITS file for the list of authors) */ +/* \VV/ **************************************************************/ +/* // * This file is distributed under the terms of the */ +/* * GNU Lesser General Public License Version 2.1 */ +/* * (see LICENSE file for the text of the license) */ +/************************************************************************/ +body { padding: 0px 0px; + margin: 0px 0px; + background-color: white } + +#page { display: block; + padding: 0px; + margin: 0px; + padding-bottom: 10px; } + +#header { display: block; + position: relative; + padding: 0; + margin: 0; + vertical-align: middle; + border-bottom-style: solid; + border-width: thin } + +#header h1 { padding: 0; + margin: 0;} + + +/* Contents */ + +#main{ display: block; + padding: 10px; + font-family: sans-serif; + font-size: 100%; + line-height: 100% } + +#main h1 { line-height: 95% } /* allow for multi-line headers */ + +#main a.idref:visited {color : #416DFF; text-decoration : none; } +#main a.idref:link {color : #416DFF; text-decoration : none; } +#main a.idref:hover {text-decoration : none; } +#main a.idref:active {text-decoration : none; } + +#main a.modref:visited {color : #416DFF; text-decoration : none; } +#main a.modref:link {color : #416DFF; text-decoration : none; } +#main a.modref:hover {text-decoration : none; } +#main a.modref:active {text-decoration : none; } + +#main .keyword { color : #cf1d1d } +#main { color: black } + +.section { background-color: rgb(60%,60%,100%); + padding-top: 13px; + padding-bottom: 13px; + padding-left: 3px; + margin-top: 5px; + margin-bottom: 5px; + font-size : 175% } + +h2.section { background-color: rgb(80%,80%,100%); + padding-left: 3px; + padding-top: 12px; + padding-bottom: 10px; + font-size : 130% } + +h3.section { background-color: rgb(90%,90%,100%); + padding-left: 3px; + padding-top: 7px; + padding-bottom: 7px; + font-size : 115% } + +h4.section { +/* + background-color: rgb(80%,80%,80%); + max-width: 20em; + padding-left: 5px; + padding-top: 5px; + padding-bottom: 5px; +*/ + background-color: white; + padding-left: 0px; + padding-top: 0px; + padding-bottom: 0px; + font-size : 100%; + font-weight : bold; + text-decoration : underline; + } + +#main .doc { margin: 0px; + font-family: sans-serif; + font-size: 100%; + line-height: 125%; + max-width: 40em; + color: black; + padding: 10px; + background-color: #90bdff } + +.inlinecode { + display: inline; +/* font-size: 125%; */ + color: #666666; + font-family: monospace } + +.doc .inlinecode { + display: inline; + font-size: 120%; + color: rgb(30%,30%,70%); + font-family: monospace } + +.doc .inlinecode .id { + color: rgb(30%,30%,70%); +} + +.inlinecodenm { + display: inline; + color: #444444; +} + +.doc .code { + display: inline; + font-size: 120%; + color: rgb(30%,30%,70%); + font-family: monospace } + +.comment { + display: inline; + font-family: monospace; + color: rgb(50%,50%,80%); +} + +.code { + display: block; +/* padding-left: 15px; */ + font-size: 110%; + font-family: monospace; + } + +table.infrule { + border: 0px; + margin-left: 50px; + margin-top: 10px; + margin-bottom: 10px; +} + +td.infrule { + font-family: monospace; + text-align: center; +/* color: rgb(35%,35%,70%); */ + padding: 0px; + line-height: 100%; +} + +tr.infrulemiddle hr { + margin: 1px 0 1px 0; +} + +.infrulenamecol { + color: rgb(60%,60%,60%); + font-size: 80%; + padding-left: 1em; + padding-bottom: 0.1em +} + +/* Pied de page */ + +#footer { font-size: 65%; + font-family: sans-serif; } + +/* Identifiers: <span class="id" title="...">) */ + +.id { display: inline; } + +.id[title="constructor"] { + color: rgb(60%,0%,0%); +} + +.id[title="var"] { + color: rgb(40%,0%,40%); +} + +.id[title="variable"] { + color: rgb(40%,0%,40%); +} + +.id[title="definition"] { + color: rgb(0%,40%,0%); +} + +.id[title="abbreviation"] { + color: rgb(0%,40%,0%); +} + +.id[title="lemma"] { + color: rgb(0%,40%,0%); +} + +.id[title="instance"] { + color: rgb(0%,40%,0%); +} + +.id[title="projection"] { + color: rgb(0%,40%,0%); +} + +.id[title="method"] { + color: rgb(0%,40%,0%); +} + +.id[title="inductive"] { + color: rgb(0%,0%,80%); +} + +.id[title="record"] { + color: rgb(0%,0%,80%); +} + +.id[title="class"] { + color: rgb(0%,0%,80%); +} + +.id[title="keyword"] { + color : #cf1d1d; +/* color: black; */ +} + +/* Deprecated rules using the 'type' attribute of <span> (not xhtml valid) */ + +.id[type="constructor"] { + color: rgb(60%,0%,0%); +} + +.id[type="var"] { + color: rgb(40%,0%,40%); +} + +.id[type="variable"] { + color: rgb(40%,0%,40%); +} + +.id[type="definition"] { + color: rgb(0%,40%,0%); +} + +.id[type="abbreviation"] { + color: rgb(0%,40%,0%); +} + +.id[type="lemma"] { + color: rgb(0%,40%,0%); +} + +.id[type="instance"] { + color: rgb(0%,40%,0%); +} + +.id[type="projection"] { + color: rgb(0%,40%,0%); +} + +.id[type="method"] { + color: rgb(0%,40%,0%); +} + +.id[type="inductive"] { + color: rgb(0%,0%,80%); +} + +.id[type="record"] { + color: rgb(0%,0%,80%); +} + +.id[type="class"] { + color: rgb(0%,0%,80%); +} + +.id[type="keyword"] { + color : #cf1d1d; +/* color: black; */ +} + +.inlinecode .id { + color: rgb(0%,0%,0%); +} + + +/* TOC */ + +#toc h2 { + padding: 10px; + background-color: rgb(60%,60%,100%); +} + +#toc li { + padding-bottom: 8px; +} + +/* Index */ + +#index { + margin: 0; + padding: 0; + width: 100%; +} + +#index #frontispiece { + margin: 1em auto; + padding: 1em; + width: 60%; +} + +.booktitle { font-size : 140% } +.authors { font-size : 90%; + line-height: 115%; } +.moreauthors { font-size : 60% } + +#index #entrance { + text-align: center; +} + +#index #entrance .spacer { + margin: 0 30px 0 30px; +} + +#index #footer { + position: absolute; + bottom: 0; +} + +.paragraph { + height: 0.75em; +} + +ul.doclist { + margin-top: 0em; + margin-bottom: 0em; +} diff --git a/doc/sphinx/dune b/doc/sphinx/dune new file mode 100644 index 0000000000..353d58c676 --- /dev/null +++ b/doc/sphinx/dune @@ -0,0 +1,8 @@ +(dirs :standard _static) + +(rule (targets README.gen.rst) + (deps (source_tree ../tools/coqrst) README.template.rst) + (action (run ../tools/coqrst/regen_readme.py %{targets}))) + +(alias (name refman-html) + (action (diff README.rst README.gen.rst))) diff --git a/doc/sphinx/genindex.rst b/doc/sphinx/genindex.rst new file mode 100644 index 0000000000..29f792b3aa --- /dev/null +++ b/doc/sphinx/genindex.rst @@ -0,0 +1,7 @@ +:orphan: + +.. hack to get index in TOC + +----- +Index +----- diff --git a/doc/sphinx/history.rst b/doc/sphinx/history.rst new file mode 100644 index 0000000000..0f5b991ba4 --- /dev/null +++ b/doc/sphinx/history.rst @@ -0,0 +1,1449 @@ +-------------------- +Early history of Coq +-------------------- + +Historical roots +---------------- + +Coq is a proof assistant for higher-order logic, allowing the +development of computer programs consistent with their formal +specification. It is the result of about ten years [#years]_ of research +of the Coq project. We shall briefly survey here three main aspects: the +*logical language* in which we write our axiomatizations and +specifications, the *proof assistant* which allows the development of +verified mathematical proofs, and the *program extractor* which +synthesizes computer programs obeying their formal specifications, +written as logical assertions in the language. + +The logical language used by |Coq| is a variety of type theory, called the +*Calculus of Inductive Constructions*. Without going back to Leibniz and +Boole, we can date the creation of what is now called mathematical logic +to the work of Frege and Peano at the turn of the century. The discovery +of antinomies in the free use of predicates or comprehension principles +prompted Russell to restrict predicate calculus with a stratification of +*types*. This effort culminated with *Principia Mathematica*, the first +systematic attempt at a formal foundation of mathematics. A +simplification of this system along the lines of simply typed +λ-calculus occurred with Church’s *Simple Theory of +Types*. The λ-calculus notation, originally used for +expressing functionality, could also be used as an encoding of natural +deduction proofs. This Curry-Howard isomorphism was used by N. de Bruijn +in the *Automath* project, the first full-scale attempt to develop and +mechanically verify mathematical proofs. This effort culminated with +Jutting’s verification of Landau’s *Grundlagen* in the 1970’s. +Exploiting this Curry-Howard isomorphism, notable achievements in proof +theory saw the emergence of two type-theoretic frameworks; the first +one, Martin-Löf’s *Intuitionistic Theory of Types*, attempts a new +foundation of mathematics on constructive principles. The second one, +Girard’s polymorphic λ-calculus :math:`F_\omega`, is a +very strong functional system in which we may represent higher-order +logic proof structures. Combining both systems in a higher-order +extension of the Automath language, T. Coquand presented in 1985 the +first version of the *Calculus of Constructions*, CoC. This strong +logical system allowed powerful axiomatizations, but direct inductive +definitions were not possible, and inductive notions had to be defined +indirectly through functional encodings, which introduced inefficiencies +and awkwardness. The formalism was extended in 1989 by T. Coquand and C. +Paulin with primitive inductive definitions, leading to the current +*Calculus of Inductive Constructions*. This extended formalism is not +rigorously defined here. Rather, numerous concrete examples are +discussed. We refer the interested reader to relevant research papers +for more information about the formalism, its meta-theoretic properties, +and semantics. However, it should not be necessary to understand this +theoretical material in order to write specifications. It is possible to +understand the Calculus of Inductive Constructions at a higher level, as +a mixture of predicate calculus, inductive predicate definitions +presented as typed PROLOG, and recursive function definitions close to +the language ML. + +Automated theorem-proving was pioneered in the 1960’s by Davis and +Putnam in propositional calculus. A complete mechanization (in the sense +of a semidecision procedure) of classical first-order logic was +proposed in 1965 by J.A. Robinson, with a single uniform inference rule +called *resolution*. Resolution relies on solving equations in free +algebras (i.e. term structures), using the *unification algorithm*. Many +refinements of resolution were studied in the 1970’s, but few convincing +implementations were realized, except of course that PROLOG is in some +sense issued from this effort. A less ambitious approach to proof +development is computer-aided proof-checking. The most notable +proof-checkers developed in the 1970’s were LCF, designed by R. Milner +and his colleagues at U. Edinburgh, specialized in proving properties +about denotational semantics recursion equations, and the Boyer and +Moore theorem-prover, an automation of primitive recursion over +inductive data types. While the Boyer-Moore theorem-prover attempted to +synthesize proofs by a combination of automated methods, LCF constructed +its proofs through the programming of *tactics*, written in a high-level +functional meta-language, ML. + +The salient feature which clearly distinguishes our proof assistant from +say LCF or Boyer and Moore’s, is its possibility to extract programs +from the constructive contents of proofs. This computational +interpretation of proof objects, in the tradition of Bishop’s +constructive mathematics, is based on a realizability interpretation, in +the sense of Kleene, due to C. Paulin. The user must just mark his +intention by separating in the logical statements the assertions stating +the existence of a computational object from the logical assertions +which specify its properties, but which may be considered as just +comments in the corresponding program. Given this information, the +system automatically extracts a functional term from a consistency proof +of its specifications. This functional term may be in turn compiled into +an actual computer program. This methodology of extracting programs from +proofs is a revolutionary paradigm for software engineering. Program +synthesis has long been a theme of research in artificial intelligence, +pioneered by R. Waldinger. The Tablog system of Z. Manna and R. +Waldinger allows the deductive synthesis of functional programs from +proofs in tableau form of their specifications, written in a variety of +first-order logic. Development of a systematic *programming logic*, +based on extensions of Martin-Löf’s type theory, was undertaken at +Cornell U. by the Nuprl team, headed by R. Constable. The first actual +program extractor, PX, was designed and implemented around 1985 by S. +Hayashi from Kyoto University. It allows the extraction of a LISP +program from a proof in a logical system inspired by the logical +formalisms of S. Feferman. Interest in this methodology is growing in +the theoretical computer science community. We can foresee the day when +actual computer systems used in applications will contain certified +modules, automatically generated from a consistency proof of their +formal specifications. We are however still far from being able to use +this methodology in a smooth interaction with the standard tools from +software engineering, i.e. compilers, linkers, run-time systems taking +advantage of special hardware, debuggers, and the like. We hope that |Coq| +can be of use to researchers interested in experimenting with this new +methodology. + +.. [#years] At the time of writting, i.e. 1995. + +Versions 1 to 5 +--------------- + +.. note:: + This summary was written in 1995 together with the previous + section and formed the initial version of the Credits chapter. + + A more comprehensive description of these early versions is available + in the following subsections, which come from a document written in + September 2015 by Gérard Huet, Thierry Coquand and Christine Paulin. + +A first implementation of CoC was started in 1984 by G. Huet and T. +Coquand. Its implementation language was CAML, a functional programming +language from the ML family designed at INRIA in Rocquencourt. The core +of this system was a proof-checker for CoC seen as a typed +λ-calculus, called the *Constructive Engine*. This engine +was operated through a high-level notation permitting the declaration of +axioms and parameters, the definition of mathematical types and objects, +and the explicit construction of proof objects encoded as +λ-terms. A section mechanism, designed and implemented by +G. Dowek, allowed hierarchical developments of mathematical theories. +This high-level language was called the *Mathematical Vernacular*. +Furthermore, an interactive *Theorem Prover* permitted the incremental +construction of proof trees in a top-down manner, subgoaling recursively +and backtracking from dead-ends. The theorem prover executed tactics +written in CAML, in the LCF fashion. A basic set of tactics was +predefined, which the user could extend by his own specific tactics. +This system (Version 4.10) was released in 1989. Then, the system was +extended to deal with the new calculus with inductive types by C. +Paulin, with corresponding new tactics for proofs by induction. A new +standard set of tactics was streamlined, and the vernacular extended for +tactics execution. A package to compile programs extracted from proofs +to actual computer programs in CAML or some other functional language +was designed and implemented by B. Werner. A new user-interface, relying +on a CAML-X interface by D. de Rauglaudre, was designed and implemented +by A. Felty. It allowed operation of the theorem-prover through the +manipulation of windows, menus, mouse-sensitive buttons, and other +widgets. This system (Version 5.6) was released in 1991. + +Coq was ported to the new implementation Caml-light of X. Leroy and D. +Doligez by D. de Rauglaudre (Version 5.7) in 1992. A new version of |Coq| +was then coordinated by C. Murthy, with new tools designed by C. Parent +to prove properties of ML programs (this methodology is dual to program +extraction) and a new user-interaction loop. This system (Version 5.8) +was released in May 1993. A Centaur interface CTCoq was then developed +by Y. Bertot from the Croap project from INRIA-Sophia-Antipolis. + +In parallel, G. Dowek and H. Herbelin developed a new proof engine, +allowing the general manipulation of existential variables consistently +with dependent types in an experimental version of |Coq| (V5.9). + +The version V5.10 of |Coq| is based on a generic system for manipulating +terms with binding operators due to Chet Murthy. A new proof engine +allows the parallel development of partial proofs for independent +subgoals. The structure of these proof trees is a mixed representation +of derivation trees for the Calculus of Inductive Constructions with +abstract syntax trees for the tactics scripts, allowing the navigation +in a proof at various levels of details. The proof engine allows generic +environment items managed in an object-oriented way. This new +architecture, due to C. Murthy, supports several new facilities which +make the system easier to extend and to scale up: + +- User-programmable tactics are allowed + +- It is possible to separately verify development modules, and to load + their compiled images without verifying them again - a quick + relocation process allows their fast loading + +- A generic parsing scheme allows user-definable notations, with a + symmetric table-driven pretty-printer + +- Syntactic definitions allow convenient abbreviations + +- A limited facility of meta-variables allows the automatic synthesis + of certain type expressions, allowing generic notations for e.g. + equality, pairing, and existential quantification. + +In the Fall of 1994, C. Paulin-Mohring replaced the structure of +inductively defined types and families by a new structure, allowing the +mutually recursive definitions. P. Manoury implemented a translation of +recursive definitions into the primitive recursive style imposed by the +internal recursion operators, in the style of the ProPre system. C. +Muñoz implemented a decision procedure for intuitionistic propositional +logic, based on results of R. Dyckhoff. J.C. Filliâtre implemented a +decision procedure for first-order logic without contraction, based on +results of J. Ketonen and R. Weyhrauch. Finally C. Murthy implemented a +library of inversion tactics, relieving the user from tedious +definitions of “inversion predicates”. + +| Rocquencourt, Feb. 1st 1995 +| Gérard Huet +| + +Version 1 +~~~~~~~~~ + +This software is a prototype type-checker for a higher-order logical +formalism known as the Theory of Constructions, presented in his PhD +thesis by Thierry Coquand, with influences from Girard's system F and +de Bruijn's Automath. The metamathematical analysis of the system is +the PhD work of Thierry Coquand. The software is mostly the work of +Gérard Huet. Most of the mathematical examples verified with the +software are due to Thierry Coquand. + +The programming language of the CONSTR software (as it was called at +the time) was a version of ML adapted from the Edinburgh LCF system +and running on a LISP backend. The main improvements from the original +LCF ML were that ML was compiled rather than interpreted (Gérard Huet +building on the original translator by Lockwood Morris), and that it +was enriched by recursively defined types (work of Guy +Cousineau). This ancestor of CAML was used and improved by Larry +Paulson for his implementation of Cambridge LCF. + +Software developments of this prototype occurred from late 1983 to +early 1985. + +Version 1.10 was frozen on December 22nd 1984. It is the version used +for the examples in Thierry Coquand's thesis, defended on January 31st +1985. There was a unique binding operator, used both for universal +quantification (dependent product) at the level of types and +functional abstraction (λ) at the level of terms/proofs, in the manner +of Automath. Substitution (λ-reduction) was implemented using de +Bruijn's indexes. + +Version 1.11 was frozen on February 19th, 1985. It is the version used +for the examples in the paper: T. Coquand, G. Huet. *Constructions: A +Higher Order Proof System for Mechanizing Mathematics* :cite:`CH85`. + +Christine Paulin joined the team at this point, for her DEA research +internship. In her DEA memoir (August 1985) she presents developments +for the *lambo* function – :math:`\text{lambo}(f)(n)` computes the minimal +:math:`m` such that :math:`f(m)` is greater than :math:`n`, for :math:`f` +an increasing integer function, a challenge for constructive mathematics. +She also encoded the majority voting algorithm of Boyer and Moore. + +Version 2 +~~~~~~~~~ + +The formal system, now renamed as the *Calculus of Constructions*, was +presented with a proof of consistency and comparisons with proof +systems of Per Martin Löf, Girard, and the Automath family of N. de +Bruijn, in the paper: T. Coquand and G. Huet. *The Calculus of +Constructions* :cite:`CH88`. + +An abstraction of the software design, in the form of an abstract +machine for proof checking, and a fuller sequence of mathematical +developments was presented in: T. Coquand, G. Huet. *Concepts +Mathématiques et Informatiques Formalisés dans le Calcul des +Constructions* :cite:`CH87`. + +Version 2.8 was frozen on December 16th, 1985, and served for +developing the examples in the above papers. + +This calculus was then enriched in version 2.9 with a cumulative +hierarchy of universes. Universe levels were initially explicit +natural numbers. Another improvement was the possibility of automatic +synthesis of implicit type arguments, relieving the user of tedious +redundant declarations. + +Christine Paulin wrote an article *Algorithm development in the +Calculus of Constructions* :cite:`P86`. Besides *lambo* and *majority*, +she presents *quicksort* and a text formatting algorithm. + +Version 2.13 of the Calculus of Constructions with universes was +frozen on June 25th, 1986. + +A synthetic presentation of type theory along constructive lines with +ML algorithms was given by Gérard Huet in his May 1986 CMU course +notes *Formal Structures for Computation and Deduction*. Its chapter +*Induction and Recursion in the Theory of Constructions* was presented +as an invited paper at the Joint Conference on Theory and Practice of +Software Development TAPSOFT’87 at Pise in March 1987, and published +as *Induction Principles Formalized in the Calculus of +Constructions* :cite:`H88`. + +Version 3 +~~~~~~~~~ + +This version saw the beginning of proof automation, with a search +algorithm inspired from PROLOG and the applicative logic programming +programs of the course notes *Formal structures for computation and +deduction*. The search algorithm was implemented in ML by Thierry +Coquand. The proof system could thus be used in two modes: proof +verification and proof synthesis, with tactics such as ``AUTO``. + +The implementation language was now called CAML, for Categorical +Abstract Machine Language. It used as backend the LLM3 virtual machine +of Le Lisp by Jérôme Chailloux. The main developers of CAML were +Michel Mauny, Ascander Suarez and Pierre Weis. + +V3.1 was started in the summer of 1986, V3.2 was frozen at the end of +November 1986. V3.4 was developed in the first half of 1987. + +Thierry Coquand held a post-doctoral position in Cambrige University +in 1986-87, where he developed a variant implementation in SML, with +which he wrote some developments on fixpoints in Scott's domains. + +Version 4 +~~~~~~~~~ + +This version saw the beginning of program extraction from proofs, with +two varieties of the type ``Prop`` of propositions, indicating +constructive intent. The proof extraction algorithms were implemented +by Christine Paulin-Mohring. + +V4.1 was frozen on July 24th, 1987. It had a first identified library +of mathematical developments (directory ``exemples``), with libraries +``Logic`` (containing impredicative encodings of intuitionistic logic and +algebraic primitives for booleans, natural numbers and list), ``Peano`` +developing second-order Peano arithmetic, ``Arith`` defining addition, +multiplication, euclidean division and factorial. Typical developments +were the Knaster-Tarski theorem and Newman's lemma from rewriting +theory. + +V4.2 was a joint development of a team consisting of Thierry Coquand, +Gérard Huet and Christine Paulin-Mohring. A file V4.2.log records the +log of changes. It was frozen on September 1987 as the last version +implemented in CAML 2.3, and V4.3 followed on CAML 2.5, a more stable +development system. + +V4.3 saw the first top-level of the system. Instead of evaluating +explicit quotations, the user could develop his mathematics in a +high-level language called the mathematical vernacular (following +Automath terminology). The user could develop files in the vernacular +notation (with ``.v`` extension) which were now separate from the ``ml`` +sources of the implementation. Gilles Dowek joined the team to +develop the vernacular language as his DEA internship research. + +A notion of sticky constant was introduced, in order to keep names of +lemmas when local hypotheses of proofs were discharged. This gave a +notion of global mathematical environment with local sections. + +Another significant practical change was that the system, originally +developped on the VAX central computer of our lab, was transferred on +SUN personal workstations, allowing a level of distributed +development. The extraction algorithm was modified, with three +annotations ``Pos``, ``Null`` and ``Typ`` decorating the sorts ``Prop`` +and ``Type``. + +Version 4.3 was frozen at the end of November 1987, and was +distributed to an early community of users (among those were Hugo +Herbelin and Loic Colson). + +V4.4 saw the first version of (encoded) inductive types. Now natural +numbers could be defined as:: + + [source, coq] + Inductive NAT : Prop = O : NAT | Succ : NAT->NAT. + +These inductive types were encoded impredicatively in the calculus, +using a subsystem *rec* due to Christine Paulin. V4.4 was frozen on +March 6th 1988. + +Version 4.5 was the first one to support inductive types and program +extraction. Its banner was *Calcul des Constructions avec +Réalisations et Synthèse*. The vernacular language was enriched to +accommodate extraction commands. + +The verification engine design was presented as: G. Huet. *The +Constructive Engine*. Version 4.5. Invited Conference, 2nd European +Symposium on Programming, Nancy, March 88. The final paper, +describing the V4.9 implementation, appeared in: A perspective in +Theoretical Computer Science, Commemorative Volume in memory of Gift +Siromoney, Ed. R. Narasimhan, World Scientific Publishing, 1989. + +Version 4.5 was demonstrated in June 1988 at the YoP Institute on +Logical Foundations of Functional Programming organized by Gérard Huet +at Austin, Texas. + +Version 4.6 was started during the summer of 1988. Its main +improvement was the complete rehaul of the proof synthesis engine by +Thierry Coquand, with a tree structure of goals. + +Its source code was communicated to Randy Pollack on September 2nd +1988. It evolved progressively into LEGO, proof system for Luo's +formalism of Extended Calculus of Constructions. + +The discharge tactic was modified by Gérard Huet to allow for +inter-dependencies in discharged lemmas. Christine Paulin improved the +inductive definition scheme in order to accommodate predicates of any +arity. + +Version 4.7 was started on September 6th, 1988. + +This version starts exploiting the CAML notion of module in order to +improve the modularity of the implementation. Now the term verifier is +identified as a proper module Machine, which the structure of its +internal data structures being hidden and thus accessible only through +the legitimate operations. This machine (the constructive engine) was +the trusted core of the implementation. The proof synthesis mechanism +was a separate proof term generator. Once a complete proof term was +synthesized with the help of tactics, it was entirely re-checked by +the engine. Thus there was no need to certify the tactics, and the +system took advantage of this fact by having tactics ignore the +universe levels, universe consistency check being relegated to the +final type-checking pass. This induced a certain puzzlement in early +users who saw, after a successful proof search, their ``QED`` followed +by silence, followed by a failure message due to a universe +inconsistency… + +The set of examples comprise set theory experiments by Hugo Herbelin, +and notably the Schroeder-Bernstein theorem. + +Version 4.8, started on October 8th, 1988, saw a major +re-implementation of the abstract syntax type ``constr``, separating +variables of the formalism and metavariables denoting incomplete terms +managed by the search mechanism. A notion of level (with three values +``TYPE``, ``OBJECT`` and ``PROOF``) is made explicit and a type judgement +clarifies the constructions, whose implementation is now fully +explicit. Structural equality is speeded up by using pointer equality, +yielding spectacular improvements. Thierry Coquand adapts the proof +synthesis to the new representation, and simplifies pattern matching +to first-order predicate calculus matching, with important performance +gain. + +A new representation of the universe hierarchy is then defined by +Gérard Huet. Universe levels are now implemented implicitly, through +a hidden graph of abstract levels constrained with an order relation. +Checking acyclicity of the graph insures well-foundedness of the +ordering, and thus consistency. This was documented in a memo *Adding +Type:Type to the Calculus of Constructions* which was never published. + +The development version is released as a stable 4.8 at the end of +1988. + +Version 4.9 is released on March 1st 1989, with the new "elastic" +universe hierarchy. + +The spring of 1989 saw the first attempt at documenting the system +usage, with a number of papers describing the formalism: + +- *Metamathematical Investigations of a Calculus of Constructions*, by + Thierry Coquand :cite:`C90`, + +- *Inductive definitions in the Calculus of Constructions*, by + Christine Paulin-Mohrin, + +- *Extracting Fω's programs from proofs in the Calculus of + Constructions*, by Christine Paulin-Mohring* :cite:`P89`, + +- *The Constructive Engine*, by Gérard Huet :cite:`H89`, + +as well as a number of user guides: + +- *A short user's guide for the Constructions*, Version 4.10, by Gérard Huet +- *A Vernacular Syllabus*, by Gilles Dowek. +- *The Tactics Theorem Prover, User's guide*, Version 4.10, by Thierry + Coquand. + +Stable V4.10, released on May 1st, 1989, was then a mature system, +distributed with CAML V2.6. + +In the mean time, Thierry Coquand and Christine Paulin-Mohring had +been investigating how to add native inductive types to the Calculus +of Constructions, in the manner of Per Martin-Löf's Intuitionistic +Type Theory. The impredicative encoding had already been presented in: +F. Pfenning and C. Paulin-Mohring. *Inductively defined types in the +Calculus of Constructions* :cite:`PP90`. An extension of the calculus +with primitive inductive types appeared in: T. Coquand and +C. Paulin-Mohring. *Inductively defined types* :cite:`CP90`. + +This led to the Calculus of Inductive Constructions, logical formalism +implemented in Versions 5 upward of the system, and documented in: +C. Paulin-Mohring. *Inductive Definitions in the System Coq - Rules +and Properties* :cite:`P93`. + +The last version of CONSTR is Version 4.11, which was last distributed +in the spring of 1990. It was demonstrated at the first workshop of +the European Basic Research Action Logical Frameworks In Sophia +Antipolis in May 1990. + +Version 5 +~~~~~~~~~ + +At the end of 1989, Version 5.1 was started, and renamed as the system +Coq for the Calculus of Inductive Constructions. It was then ported to +the new stand-alone implementation of ML called Caml-light. + +In 1990 many changes occurred. Thierry Coquand left for Chalmers +University in Göteborg. Christine Paulin-Mohring took a CNRS +researcher position at the LIP laboratory of École Normale Supérieure +de Lyon. Project Formel was terminated, and gave rise to two teams: +Cristal at INRIA-Roquencourt, that continued developments in +functional programming with Caml-light then OCaml, and Coq, continuing +the type theory research, with a joint team headed by Gérard Huet at +INRIA-Rocquencourt and Christine Paulin-Mohring at the LIP laboratory +of CNRS-ENS Lyon. + +Chetan Murthy joined the team in 1991 and became the main software +architect of Version 5. He completely rehauled the implementation for +efficiency. Versions 5.6 and 5.8 were major distributed versions, +with complete documentation and a library of users' developements. The +use of the RCS revision control system, and systematic ChangeLog +files, allow a more precise tracking of the software developments. + +| September 2015 + +| Thierry Coquand, Gérard Huet and Christine Paulin-Mohring. +| + +Versions 6 +---------- + +Version 6.1 +~~~~~~~~~~~ + +The present version 6.1 of |Coq| is based on the V5.10 architecture. It +was ported to the new language Objective Caml by Bruno Barras. The +underlying framework has slightly changed and allows more conversions +between sorts. + +The new version provides powerful tools for easier developments. + +Cristina Cornes designed an extension of the |Coq| syntax to allow +definition of terms using a powerful pattern matching analysis in the +style of ML programs. + +Amokrane Saïbi wrote a mechanism to simulate inheritance between types +families extending a proposal by Peter Aczel. He also developed a +mechanism to automatically compute which arguments of a constant may be +inferred by the system and consequently do not need to be explicitly +written. + +Yann Coscoy designed a command which explains a proof term using natural +language. Pierre Crégut built a new tactic which solves problems in +quantifier-free Presburger Arithmetic. Both functionalities have been +integrated to the |Coq| system by Hugo Herbelin. + +Samuel Boutin designed a tactic for simplification of commutative rings +using a canonical set of rewriting rules and equality modulo +associativity and commutativity. + +Finally the organisation of the |Coq| distribution has been supervised by +Jean-Christophe Filliâtre with the help of Judicaël Courant and Bruno +Barras. + +| Lyon, Nov. 18th 1996 +| Christine Paulin +| + +Version 6.2 +~~~~~~~~~~~ + +In version 6.2 of |Coq|, the parsing is done using camlp4, a preprocessor +and pretty-printer for CAML designed by Daniel de Rauglaudre at INRIA. +Daniel de Rauglaudre made the first adaptation of |Coq| for camlp4, this +work was continued by Bruno Barras who also changed the structure of |Coq| +abstract syntax trees and the primitives to manipulate them. The result +of these changes is a faster parsing procedure with greatly improved +syntax-error messages. The user-interface to introduce grammar or +pretty-printing rules has also changed. + +Eduardo Giménez redesigned the internal tactic libraries, giving uniform +names to Caml functions corresponding to |Coq| tactic names. + +Bruno Barras wrote new, more efficient reduction functions. + +Hugo Herbelin introduced more uniform notations in the |Coq| specification +language: the definitions by fixpoints and pattern matching have a more +readable syntax. Patrick Loiseleur introduced user-friendly notations +for arithmetic expressions. + +New tactics were introduced: Eduardo Giménez improved the mechanism to +introduce macros for tactics, and designed special tactics for +(co)inductive definitions; Patrick Loiseleur designed a tactic to +simplify polynomial expressions in an arbitrary commutative ring which +generalizes the previous tactic implemented by Samuel Boutin. +Jean-Christophe Filliâtre introduced a tactic for refining a goal, using +a proof term with holes as a proof scheme. + +David Delahaye designed the tool to search an object in the library +given its type (up to isomorphism). + +Henri Laulhère produced the |Coq| distribution for the Windows +environment. + +Finally, Hugo Herbelin was the main coordinator of the |Coq| documentation +with principal contributions by Bruno Barras, David Delahaye, +Jean-Christophe Filliâtre, Eduardo Giménez, Hugo Herbelin and Patrick +Loiseleur. + +| Orsay, May 4th 1998 +| Christine Paulin +| + +Version 6.3 +~~~~~~~~~~~ + +The main changes in version V6.3 were the introduction of a few new +tactics and the extension of the guard condition for fixpoint +definitions. + +B. Barras extended the unification algorithm to complete partial terms +and fixed various tricky bugs related to universes. + +D. Delahaye developed the ``AutoRewrite`` tactic. He also designed the +new behavior of ``Intro`` and provided the tacticals ``First`` and +``Solve``. + +J.-C. Filliâtre developed the ``Correctness`` tactic. + +\E. Giménez extended the guard condition in fixpoints. + +H. Herbelin designed the new syntax for definitions and extended the +``Induction`` tactic. + +P. Loiseleur developed the ``Quote`` tactic and the new design of the +``Auto`` tactic, he also introduced the index of errors in the +documentation. + +C. Paulin wrote the ``Focus`` command and introduced the reduction +functions in definitions, this last feature was proposed by J.-F. +Monin from CNET Lannion. + +| Orsay, Dec. 1999 +| Christine Paulin +| + +Versions 7 +---------- + +Summary of changes +~~~~~~~~~~~~~~~~~~ + +The version V7 is a new implementation started in September 1999 by +Jean-Christophe Filliâtre. This is a major revision with respect to the +internal architecture of the system. The |Coq| version 7.0 was distributed +in March 2001, version 7.1 in September 2001, version 7.2 in January +2002, version 7.3 in May 2002 and version 7.4 in February 2003. + +Jean-Christophe Filliâtre designed the architecture of the new system. +He introduced a new representation for environments and wrote a new +kernel for type checking terms. His approach was to use functional +data-structures in order to get more sharing, to prepare the addition of +modules and also to get closer to a certified kernel. + +Hugo Herbelin introduced a new structure of terms with local +definitions. He introduced “qualified” names, wrote a new +pattern matching compilation algorithm and designed a more compact +algorithm for checking the logical consistency of universes. He +contributed to the simplification of |Coq| internal structures and the +optimisation of the system. He added basic tactics for forward reasoning +and coercions in patterns. + +David Delahaye introduced a new language for tactics. General tactics +using pattern matching on goals and context can directly be written from +the |Coq| toplevel. He also provided primitives for the design of +user-defined tactics in Caml. + +Micaela Mayero contributed the library on real numbers. Olivier +Desmettre extended this library with axiomatic trigonometric functions, +square, square roots, finite sums, Chasles property and basic plane +geometry. + +Jean-Christophe Filliâtre and Pierre Letouzey redesigned a new +extraction procedure from |Coq| terms to Caml or Haskell programs. This +new extraction procedure, unlike the one implemented in previous version +of |Coq| is able to handle all terms in the Calculus of Inductive +Constructions, even involving universes and strong elimination. P. +Letouzey adapted user contributions to extract ML programs when it was +sensible. Jean-Christophe Filliâtre wrote ``coqdoc``, a documentation +tool for |Coq| libraries usable from version 7.2. + +Bruno Barras improved the efficiency of the reduction algorithm and the +confidence level in the correctness of |Coq| critical type checking +algorithm. + +Yves Bertot designed the ``SearchPattern`` and ``SearchRewrite`` tools +and the support for the pcoq interface +(http://www-sop.inria.fr/lemme/pcoq/). + +Micaela Mayero and David Delahaye introduced Field, a decision tactic +for commutative fields. + +Christine Paulin changed the elimination rules for empty and singleton +propositional inductive types. + +Loïc Pottier developed Fourier, a tactic solving linear inequalities on +real numbers. + +Pierre Crégut developed a new, reflection-based version of the Omega +decision procedure. + +Claudio Sacerdoti Coen designed an XML output for the |Coq| modules to be +used in the Hypertextual Electronic Library of Mathematics (HELM cf +http://www.cs.unibo.it/helm). + +A library for efficient representation of finite maps using binary trees +contributed by Jean Goubault was integrated in the basic theories. + +Pierre Courtieu developed a command and a tactic to reason on the +inductive structure of recursively defined functions. + +Jacek Chrząszcz designed and implemented the module system of |Coq| whose +foundations are in Judicaël Courant’s PhD thesis. + +The development was coordinated by C. Paulin. + +Many discussions within the Démons team and the LogiCal project +influenced significantly the design of |Coq| especially with J. Courant, +J. Duprat, J. Goubault, A. Miquel, C. Marché, B. Monate and B. Werner. + +Intensive users suggested improvements of the system : Y. Bertot, L. +Pottier, L. Théry, P. Zimmerman from INRIA, C. Alvarado, P. Crégut, +J.-F. Monin from France Telecom R & D. + +| Orsay, May. 2002 +| Hugo Herbelin & Christine Paulin +| + +Details of changes in 7.0 and 7.1 +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Notes: + +- items followed by (**) are important sources of incompatibilities +- items followed by (*) may exceptionally be sources of incompatibilities +- items followed by (+) have been introduced in version 7.0 + + +Main novelties +^^^^^^^^^^^^^^ + +References are to Coq 7.1 reference manual + +- New primitive let-in construct (see sections 1.2.8 and ) +- Long names (see sections 2.6 and 2.7) +- New high-level tactic language (see chapter 10) +- Improved search facilities (see section 5.2) +- New extraction algorithm managing the Type level (see chapter 17) +- New rewriting tactic for arbitrary equalities (see chapter 19) +- New tactic Field to decide equalities on commutative fields (see 7.11) +- New tactic Fourier to solve linear inequalities on reals numbers (see 7.11) +- New tactics for induction/case analysis in "natural" style (see 7.7) +- Deep restructuration of the code (safer, simpler and more efficient) +- Export of theories to XML for publishing and rendering purposes + (see http://www.cs.unibo.it/helm) + + +Details of changes +^^^^^^^^^^^^^^^^^^ + +Language: new "let-in" construction +*********************************** + +- New construction for local definitions (let-in) with syntax [x:=u]t (*)(+) + +- Local definitions allowed in Record (a.k.a. record à la Randy Pollack) + + +Language: long names +******************** + +- Each construction has a unique absolute names built from a base + name, the name of the module in which they are defined (Top if in + coqtop), and possibly an arbitrary long sequence of directory (e.g. + "Coq.Lists.PolyList.flat_map" where "Coq" means that "flat_map" is part + of Coq standard library, "Lists" means it is defined in the Lists + library and "PolyList" means it is in the file Polylist) (+) + +- Constructions can be referred by their base name, or, in case of + conflict, by a "qualified" name, where the base name is prefixed + by the module name (and possibly by a directory name, and so + on). A fully qualified name is an absolute name which always refer + to the construction it denotes (to preserve the visibility of + all constructions, no conflict is allowed for an absolute name) (+) + +- Long names are available for modules with the possibility of using + the directory name as a component of the module full name (with + option -R to coqtop and coqc, or command Add LoadPath) (+) + +- Improved conflict resolution strategy (the Unix PATH model), + allowing more constructions to be referred just by their base name + + +Language: miscellaneous +*********************** + +- The names of variables for Record projections _and_ for induction principles + (e.g. sum_ind) is now based on the first letter of their type (main + source of incompatibility) (**)(+) + +- Most typing errors have now a precise location in the source (+) + +- Slightly different mechanism to solve "?" (*)(+) + +- More arguments may be considered implicit at section closing (*)(+) + +- Bug with identifiers ended by a number greater than 2^30 fixed (+) + +- New visibility discipline for Remark, Fact and Local: Remark's and + Fact's now survive at the end of section, but are only accessible using a + qualified names as soon as their strength expires; Local's disappear and + are moved into local definitions for each construction persistent at + section closing + + +Language: Cases +*************** + +- Cases no longer considers aliases inferable from dependencies in types (*)(+) + +- A redundant clause in Cases is now an error (*) + + +Reduction +********* + +- New reduction flags "Zeta" and "Evar" in Eval Compute, for inlining of + local definitions and instantiation of existential variables + +- Delta reduction flag does not perform Zeta and Evar reduction any more (*) + +- Constants declared as opaque (using Qed) can no longer become + transparent (a constant intended to be alternatively opaque and + transparent must be declared as transparent (using Defined)); a risk + exists (until next Coq version) that Simpl and Hnf reduces opaque + constants (*) + + +New tactics +*********** + +- New set of tactics to deal with types equipped with specific + equalities (a.k.a. Setoids, e.g. nat equipped with eq_nat) [by C. Renard] + +- New tactic Assert, similar to Cut but expected to be more user-friendly + +- New tactic NewDestruct and NewInduction intended to replace Elim + and Induction, Case and Destruct in a more user-friendly way (see + restrictions in the reference manual) + +- New tactic ROmega: an experimental alternative (based on reflexion) to Omega + [by P. Crégut] + +- New tactic language Ltac (see reference manual) (+) + +- New versions of Tauto and Intuition, fully rewritten in the new Ltac + language; they run faster and produce more compact proofs; Tauto is + fully compatible but, in exchange of a better uniformity, Intuition + is slightly weaker (then use Tauto instead) (**)(+) + +- New tactic Field to decide equalities on commutative fields (as a + special case, it works on real numbers) (+) + +- New tactic Fourier to solve linear inequalities on reals numbers + [by L. Pottier] (+) + +- New tactics dedicated to real numbers: DiscrR, SplitRmult, SplitAbsolu (+) + + +Changes in existing tactics +*************************** + +- Reduction tactics in local definitions apply only to the body + +- New syntax of the form "Compute in Type of H." to require a reduction on + the types of local definitions + +- Inversion, Injection, Discriminate, ... apply also on the + quantified premises of a goal (using the "Intros until" syntax) + +- Decompose has been fixed but hypotheses may get different names (*)(+) + +- Tauto now manages uniformly hypotheses and conclusions of the form + ``t=t`` which all are considered equivalent to ``True``. Especially, + Tauto now solves goals of the form ``H : ~ t = t |- A``. + +- The "Let" tactic has been renamed "LetTac" and is now based on the + primitive "let-in" (+) + +- Elim can no longer be used with an elimination schema different from + the one defined at definition time of the inductive type. To overload + an elimination schema, use "Elim <hyp> using <name of the new schema>" + (*)(+) + +- Simpl no longer unfolds the recursive calls of a mutually defined + fixpoint (*)(+) + +- Intro now fails if the hypothesis name already exists (*)(+) + +- "Require Prolog" is no longer needed (i.e. it is available by default) (*)(+) + +- Unfold now fails on a non unfoldable identifier (*)(+) + +- Unfold also applies on definitions of the local context + +- AutoRewrite now deals only with the main goal and it is the purpose of + Hint Rewrite to deal with generated subgoals (+) + +- Redundant or incompatible instantiations in Apply ... with ... are now + correctly managed (+) + + +Efficiency +********** + +- Excessive memory uses specific to V7.0 fixed + +- Sizes of .vo files vary a lot compared to V6.3 (from -30% to +300% + depending on the developments) + +- An improved reduction strategy for lazy evaluation + +- A more economical mechanism to ensure logical consistency at the Type level; + warning: this is experimental and may produce "universes" anomalies + (please report) + + +Concrete syntax of constructions +******************************** + +- Only identifiers starting with "_" or a letter, and followed by letters, + digits, "_" or "'" are allowed (e.g. "$" and "@" are no longer allowed) (*) + +- A multiple binder like (a:A)(a,b:(P a))(Q a) is no longer parsed as + (a:A)(a0:(P a))(b:(P a))(Q a0) but as (a:A)(a0:(P a))(b:(P a0))(Q a0) (*)(+) + +- A dedicated syntax has been introduced for Reals (e.g ``3+1/x``) (+) + +- Pretty-printing of Infix notations fixed. (+) + + +Parsing and grammar extension +***************************** + +- More constraints when writing ast + + - "{...}" and the macros $LIST, $VAR, etc. now expect a metavariable + (an identifier starting with $) (*) + - identifiers should starts with a letter or "_" and be followed + by letters, digits, "_" or "'" (other characters are still + supported but it is not advised to use them) (*)(+) + +- Entry "command" in "Grammar" and quotations (<<...>> stuff) is + renamed "constr" as in "Syntax" (+) + +- New syntax "[" sentence_1 ... sentence_n"]." to group sentences (useful + for Time and to write grammar rules abbreviating several commands) (+) + +- The default parser for actions in the grammar rules (and for + patterns in the pretty-printing rules) is now the one associated to + the grammar (i.e. vernac, tactic or constr); no need then for + quotations as in <:vernac:<...>>; to return an "ast", the grammar + must be explicitly typed with tag ": ast" or ": ast list", or if a + syntax rule, by using <<...>> in the patterns (expression inside + these angle brackets are parsed as "ast"); for grammars other than + vernac, tactic or constr, you may explicitly type the action with + tags ": constr", ": tactic", or ":vernac" (**)(+) + +- Interpretation of names in Grammar rule is now based on long names, + which allows to avoid problems (or sometimes tricks;) related to + overloaded names (+) + + +New commands +************ + +- New commands "Print XML All", "Show XML Proof", ... to show or + export theories to XML to be used with Helm's publishing and rendering + tools (see http://www.cs.unibo.it/helm) (by Claudio Sacerdoti Coen) (+) + +- New commands to manually set implicit arguments (+) + + - "Implicits ident." to activate the implicit arguments mode just for ident + - "Implicits ident [num1 num2 ...]." to explicitly give which + arguments have to be considered as implicit + +- New SearchPattern/SearchRewrite (by Yves Bertot) (+) + +- New commands "Debug on"/"Debug off" to activate/deactivate the tactic + language debugger (+) + +- New commands to map physical paths to logical paths (+) + - Add LoadPath physical_dir as logical_dir + - Add Rec LoadPath physical_dir as logical_dir + + +Changes in existing commands +**************************** + +- Generalization of the usage of qualified identifiers in tactics + and commands about globals, e.g. Decompose, Eval Delta; + Hints Unfold, Transparent, Require + +- Require synchronous with Reset; Require's scope stops at Section ending (*) + +- For a module indirectly loaded by a "Require" but not exported, + the command "Import module" turns the constructions defined in the + module accessible by their short name, and activates the Grammar, + Syntax, Hint, ... declared in the module (+) + +- The scope of the "Search" command can be restricted to some modules (+) + +- Final dot in command (full stop/period) must be followed by a blank + (newline, tabulation or whitespace) (+) + +- Slight restriction of the syntax for Cbv Delta: if present, option [-myconst] + must immediately follow the Delta keyword (*)(+) + +- SearchIsos currently not supported + +- Add ML Path is now implied by Add LoadPath (+) + +- New names for the following commands (+) + + AddPath -> Add LoadPath + Print LoadPath -> Print LoadPath + DelPath -> Remove LoadPath + AddRecPath -> Add Rec LoadPath + Print Path -> Print Coercion Paths + + Implicit Arguments On -> Set Implicit Arguments + Implicit Arguments Off -> Unset Implicit Arguments + + Begin Silent -> Set Silent + End Silent -> Unset Silent. + + +Tools +***** + +- coqtop (+) + + - Two executables: coqtop.byte and coqtop.opt (if supported by the platform) + - coqtop is a link to the more efficient executable (coqtop.opt if present) + - option -full is obsolete (+) + +- do_Makefile renamed into coq_makefile (+) + +- New option -R to coqtop and coqc to map a physical directory to a logical + one (+) + +- coqc no longer needs to create a temporary file + +- No more warning if no initialization file .coqrc exists + + +Extraction +********** + +- New algorithm for extraction able to deal with "Type" (+) + (by J.-C. Filliâtre and P. Letouzey) + + +Standard library +**************** + +- New library on maps on integers (IntMap, contributed by Jean Goubault) + +- New lemmas about integer numbers [ZArith] + +- New lemmas and a "natural" syntax for reals [Reals] (+) + +- Exc/Error/Value renamed into Option/Some/None (*) + + +New user contributions +********************** + +- Constructive complex analysis and the Fundamental Theorem of Algebra [FTA] + (Herman Geuvers, Freek Wiedijk, Jan Zwanenburg, Randy Pollack, + Henk Barendregt, Nijmegen) + +- A new axiomatization of ZFC set theory [Functions_in_ZFC] + (C. Simpson, Sophia-Antipolis) + +- Basic notions of graph theory [GRAPHS-BASICS] (Jean Duprat, Lyon) + +- A library for floating-point numbers [Float] (Laurent Théry, Sylvie Boldo, + Sophia-Antipolis) + +- Formalisation of CTL and TCTL temporal logic [CtlTctl] (Carlos + Daniel Luna,Montevideo) + +- Specification and verification of the Railroad Crossing Problem + in CTL and TCTL [RailroadCrossing] (Carlos Daniel Luna,Montevideo) + +- P-automaton and the ABR algorithm [PAutomata] + (Christine Paulin, Emmanuel Freund, Orsay) + +- Semantics of a subset of the C language [MiniC] + (Eduardo Giménez, Emmanuel Ledinot, Suresnes) + +- Correctness proofs of the following imperative algorithms: + Bresenham line drawing algorithm [Bresenham], Marché's minimal edition + distance algorithm [Diff] (Jean-Christophe Filliâtre, Orsay) + +- Correctness proofs of Buchberger's algorithm [Buchberger] and RSA + cryptographic algorithm [Rsa] (Laurent Théry, Sophia-Antipolis) + +- Correctness proof of Stalmarck tautology checker algorithm + [Stalmarck] (Laurent Théry, Pierre Letouzey, Sophia-Antipolis) + + +Details of changes in 7.2 +~~~~~~~~~~~~~~~~~~~~~~~~~ + +Language + +- Automatic insertion of patterns for local definitions in the type of + the constructors of an inductive types (for compatibility with V6.3 + let-in style) +- Coercions allowed in Cases patterns +- New declaration "Canonical Structure id = t : I" to help resolution of + equations of the form (proj ?)=a; if proj(e)=a then a is canonically + equipped with the remaining fields in e, i.e. ? is instantiated by e + +Tactics + +- New tactic "ClearBody H" to clear the body of definitions in local context +- New tactic "Assert H := c" for forward reasoning +- Slight improvement in naming strategy for NewInduction/NewDestruct +- Intuition/Tauto do not perform useless unfolding and work up to conversion + +Extraction (details in plugins/extraction/CHANGES or documentation) + +- Syntax changes: there are no more options inside the extraction commands. + New commands for customization and options have been introduced instead. +- More optimizations on extracted code. +- Extraction tests are now embedded in 14 user contributions. + +Standard library + +- In [Relations], Rstar.v and Newman.v now axiom-free. +- In [Sets], Integers.v now based on nat +- In [Arith], more lemmas in Min.v, new file Max.v, tail-recursive + plus and mult added to Plus.v and Mult.v respectively +- New directory [Sorting] with a proof of heapsort (dragged from 6.3.1 lib) +- In [Reals], more lemmas in Rbase.v, new lemmas on square, square root and + trigonometric functions (R_sqr.v - Rtrigo.v); a complementary approach + and new theorems about continuity and derivability in Ranalysis.v; some + properties in plane geometry such as translation, rotation or similarity + in Rgeom.v; finite sums and Chasles property in Rsigma.v + +Bugs + +- Confusion between implicit args of locals and globals of same base name fixed +- Various incompatibilities wrt inference of "?" in V6.3.1 fixed +- Implicits in infix section variables bug fixed +- Known coercions bugs fixed + +- Apply "universe anomaly" bug fixed +- NatRing now working +- "Discriminate 1", "Injection 1", "Simplify_eq 1" now working +- NewInduction bugs with let-in and recursively dependent hypotheses fixed +- Syntax [x:=t:T]u now allowed as mentioned in documentation + +- Bug with recursive inductive types involving let-in fixed +- Known pattern-matching bugs fixed +- Known Cases elimination predicate bugs fixed +- Improved errors messages for pattern-matching and projections +- Better error messages for ill-typed Cases expressions + +Incompatibilities + +- New naming strategy for NewInduction/NewDestruct may affect 7.1 compatibility +- Extra parentheses may exceptionally be needed in tactic definitions. +- Coq extensions written in Ocaml need to be updated (see dev/changements.txt + for a description of the main changes in the interface files of V7.2) +- New behaviour of Intuition/Tauto may exceptionally lead to incompatibilities + + +Details of changes in 7.3 +~~~~~~~~~~~~~~~~~~~~~~~~~ + +Language + +- Slightly improved compilation of pattern-matching (slight source of + incompatibilities) +- Record's now accept anonymous fields "_" which does not build projections +- Changes in the allowed elimination sorts for certain class of inductive + definitions : an inductive definition without constructors + of Sort Prop can be eliminated on sorts Set and Type A "singleton" + inductive definition (one constructor with arguments in the sort Prop + like conjunction of two propositions or equality) can be eliminated + directly on sort Type (In V7.2, only the sorts Prop and Set were allowed) + +Tactics + +- New tactic "Rename x into y" for renaming hypotheses +- New tactics "Pose x:=u" and "Pose u" to add definitions to local context +- Pattern now working on partially applied subterms +- Ring no longer applies irreversible congruence laws of mult but + better applies congruence laws of plus (slight source of incompatibilities). +- Field now accepts terms to be simplified as arguments (as for Ring). This + extension has been also implemented using the toplevel tactic language. +- Intuition does no longer unfold constants except "<->" and "~". It + can be parameterized by a tactic. It also can introduce dependent + product if needed (source of incompatibilities) +- "Match Context" now matching more recent hypotheses first and failing only + on user errors and Fail tactic (possible source of incompatibilities) +- Tactic Definition's without arguments now allowed in Coq states +- Better simplification and discrimination made by Inversion (source + of incompatibilities) + +Bugs + +- "Intros H" now working like "Intro H" trying first to reduce if not a product +- Forward dependencies in Cases now taken into account +- Known bugs related to Inversion and let-in's fixed +- Bug unexpected Delta with let-in now fixed + +Extraction (details in plugins/extraction/CHANGES or documentation) + +- Signatures of extracted terms are now mostly expunged from dummy arguments. +- Haskell extraction is now operational (tested & debugged). + +Standard library + +- Some additions in [ZArith]: three files (Zcomplements.v, Zpower.v + and Zlogarithms.v) moved from plugins/omega in order to be more + visible, one Zsgn function, more induction principles (Wf_Z.v and + tail of Zcomplements.v), one more general Euclid theorem +- Peano_dec.v and Compare_dec.v now part of Arith.v + +Tools + +- new option -dump-glob to coqtop to dump globalizations (to be used by the + new documentation tool coqdoc; see http://www.lri.fr/~filliatr/coqdoc) + +User Contributions + +- CongruenceClosure (congruence closure decision procedure) + [Pierre Corbineau, ENS Cachan] +- MapleMode (an interface to embed Maple simplification procedures over + rational fractions in Coq) + [David Delahaye, Micaela Mayero, Chalmers University] +- Presburger: A formalization of Presburger's algorithm + [Laurent Thery, INRIA Sophia Antipolis] +- Chinese has been rewritten using Z from ZArith as datatype + ZChinese is the new version, Chinese the obsolete one + [Pierre Letouzey, LRI Orsay] + +Incompatibilities + +- Ring: exceptional incompatibilities (1 above 650 in submitted user + contribs, leading to a simplification) +- Intuition: does not unfold any definition except "<->" and "~" +- Cases: removal of some extra Cases in configurations of the form + "Cases ... of C _ => ... | _ D => ..." (effects on 2 definitions of + submitted user contributions necessitating the removal of now superfluous + proof steps in 3 different proofs) +- Match Context, in case of incompatibilities because of a now non + trapped error (e.g. Not_found or Failure), use instead tactic Fail + to force Match Context trying the next clause +- Inversion: better simplification and discrimination may occasionally + lead to less subgoals and/or hypotheses and different naming of hypotheses +- Unification done by Apply/Elim has been changed and may exceptionally lead + to incompatible instantiations +- Peano_dec.v and Compare_dec.v parts of Arith.v make Auto more + powerful if these files were not already required (1 occurrence of + this in submitted user contribs) + + +Changes in 7.3.1 +^^^^^^^^^^^^^^^^ + +Bug fixes + + - Corrupted Field tactic and Match Context tactic construction fixed + - Checking of names already existing in Assert added (#1386) + - Invalid argument bug in Exact tactic solved (#1387) + - Colliding bound names bug fixed (#1412) + - Wrong non-recursivity test for Record fixed (#1394) + - Out of memory/seg fault bug related to parametric inductive fixed (#1404) + - Setoid_replace/Setoid_rewrite bug wrt "==" fixed + +Misc + + - Ocaml version >= 3.06 is needed to compile Coq from sources + - Simplification of fresh names creation strategy for Assert, Pose and + LetTac (#1402) + + +Details of changes in 7.4 +~~~~~~~~~~~~~~~~~~~~~~~~~ + +Symbolic notations + +- Introduction of a notion of scope gathering notations in a consistent set; + a notation sets has been developed for nat, Z and R (undocumented) +- New command "Notation" for declaring notations simultaneously for + parsing and printing (see chap 10 of the reference manual) +- Declarations with only implicit arguments now handled (e.g. the + argument of nil can be set implicit; use !nil to refer to nil + without arguments) +- "Print Scope sc" and "Locate ntn" allows to know to what expression a + notation is bound +- New defensive strategy for printing or not implicit arguments to ensure + re-type-checkability of the printed term +- In Grammar command, the only predefined non-terminal entries are ident, + global, constr and pattern (e.g. nvar, numarg disappears); the only + allowed grammar types are constr and pattern; ast and ast list are no + longer supported; some incompatibilities in Grammar: when a syntax is a + initial segment of an other one, Grammar does not work, use Notation + +Library + +- Lemmas in Set from Compare_dec.v (le_lt_dec, ...) and Wf_nat.v + (lt_wf_rec, ...) are now transparent. This may be source of + incompatibilities. +- Syntactic Definitions Fst, Snd, Ex, All, Ex2, AllT, ExT, ExT2, + ProjS1, ProjS2, Error, Value and Except are turned to + notations. They now must be applied (incompatibilities only in + unrealistic cases). +- More efficient versions of Zmult and times (30% faster) +- Reals: the library is now divided in 6 parts (Rbase, Rfunctions, + SeqSeries, Rtrigo, Ranalysis, Integration). New tactics: Sup and + RCompute. See Reals.v for details. + +Modules + +- Beta version, see doc chap 2.5 for commands and chap 5 for theory + +Language + +- Inductive definitions now accept ">" in constructor types to declare + the corresponding constructor as a coercion. +- Idem for assumptions declarations and constants when the type is mentionned. +- The "Coercion" and "Canonical Structure" keywords now accept the + same syntax as "Definition", i.e. "hyps :=c (:t)?" or "hyps :t". +- Theorem-like declaration now accepts the syntax "Theorem thm [x:t;...] : u". +- Remark's and Fact's now definitively behave as Theorem and Lemma: when + sections are closed, the full name of a Remark or a Fact has no longer a + section part (source of incompatibilities) +- Opaque Local's (i.e. built by tactics and ended by Qed), do not + survive section closing any longer; as a side-effect, Opaque Local's + now appear in the local context of proofs; their body is hidden + though (source of incompatibilities); use one of Remark/Fact/Lemma/Theorem + instead to simulate the old behaviour of Local (the section part of + the name is not kept though) + +ML tactic and vernacular commands + +- "Grammar tactic" and "Grammar vernac" of type "ast" are no longer + supported (only "Grammar tactic simple_tactic" of type "tactic" + remains available). +- Concrete syntax for ML written vernacular commands and tactics is + now declared at ML level using camlp4 macros TACTIC EXTEND et VERNAC + COMMAND EXTEND. +- "Check n c" now "n:Check c", "Eval n ..." now "n:Eval ..." +- ``Proof with T`` (no documentation) +- SearchAbout id - prints all theorems which contain id in their type + +Tactic definitions + +- Static globalisation of identifiers and global references (source of + incompatibilities, especially, Recursive keyword is required for + mutually recursive definitions). +- New evaluation semantics: no more partial evaluation at definition time; + evaluation of all Tactic/Meta Definition, even producing terms, expect + a proof context to be evaluated (especially "()" is no longer needed). +- Debugger now shows the nesting level and the reasons of failure + +Tactics + +- Equality tactics (Rewrite, Reflexivity, Symmetry, Transitivity) now + understand JM equality +- Simpl and Change now apply to subterms also +- "Simpl f" reduces subterms whose head constant is f +- Double Induction now referring to hypotheses like "Intros until" +- "Inversion" now applies also on quantified hypotheses (naming as + for Intros until) +- NewDestruct now accepts terms with missing hypotheses +- NewDestruct and NewInduction now accept user-provided elimination scheme +- NewDestruct and NewInduction now accept user-provided introduction names +- Omega could solve goals such as ``~x<y |- x>=y`` but failed when the + hypothesis was unfolded to ``x < y -> False``. This is fixed. In addition, + it can also recognize 'False' in the hypothesis and use it to solve the + goal. +- Coercions now handled in "with" bindings +- "Subst x" replaces all ocurrences of x by t in the goal and hypotheses + when an hypothesis x=t or x:=t or t=x exists +- Fresh names for Assert and Pose now based on collision-avoiding + Intro naming strategy (exceptional source of incompatibilities) +- LinearIntuition (no documentation) +- Unfold expects a correct evaluable argument +- Clear expects existing hypotheses + +Extraction (See details in plugins/extraction/CHANGES and README): + +- An experimental Scheme extraction is provided. +- Concerning Ocaml, extracted code is now ensured to always type-check, + thanks to automatic inserting of Obj.magic. +- Experimental extraction of Coq new modules to Ocaml modules. + +Proof rendering in natural language + +- Export of theories to XML for publishing and rendering purposes now + includes proof-trees (see http://www.cs.unibo.it/helm) + +Miscellaneous + +- Printing Coercion now used through the standard keywords Set/Add, Test, Print +- "Print Term id" is an alias for "Print id" +- New switch "Unset/Set Printing Symbols" to control printing of + symbolic notations +- Two new variants of implicit arguments are available + + + ``Unset``/``Set Contextual Implicits`` tells to consider implicit also the + arguments inferable from the context (e.g. for nil or refl_eq) + + ``Unset``/``Set Strict Implicits`` tells to consider implicit only the + arguments that are inferable in any case (i.e. arguments that occurs + as argument of rigid constants in the type of the remaining arguments; + e.g. the witness of an existential is not strict since it can vanish when + applied to a predicate which does not use its argument) + +Incompatibilities + +- "Grammar tactic ... : ast" and "Grammar vernac ... : ast" are no + longer supported, use TACTIC EXTEND and VERNAC COMMAND EXTEND on the + ML-side instead +- Transparency of le_lt_dec and co (leads to some simplification in + proofs; in some cases, incompatibilites is solved by declaring locally + opaque the relevant constant) +- Opaque Local do not now survive section closing (rename them into + Remark/Lemma/... to get them still surviving the sections; this + renaming allows also to solve incompatibilites related to now + forbidden calls to the tactic Clear) +- Remark and Fact have no longer (very) long names (use Local instead in case + of name conflict) + +Bugs + +- Improved localisation of errors in Syntactic Definitions +- Induction principle creation failure in presence of let-in fixed (#1459) +- Inversion bugs fixed (#1427 and #1437) +- Omega bug related to Set fixed (#1384) +- Type-checking inefficiency of nested destructuring let-in fixed (#1435) +- Improved handling of let-in during holes resolution phase (#1460) + +Efficiency + +- Implementation of a memory sharing strategy reducing memory + requirements by an average ratio of 3. diff --git a/doc/sphinx/index.html.rst b/doc/sphinx/index.html.rst new file mode 100644 index 0000000000..a91c6a9c5f --- /dev/null +++ b/doc/sphinx/index.html.rst @@ -0,0 +1,90 @@ +========================== +Introduction and Contents +========================== + +.. include:: introduction.rst + +Contents +-------- + +.. toctree:: + :caption: Indexes + + genindex + coq-cmdindex + coq-tacindex + coq-optindex + coq-exnindex + +.. No entries yet + * :index:`thmindex` + +.. toctree:: + :caption: Preamble + + self + history + changes + +.. toctree:: + :caption: The language + + language/gallina-specification-language + language/gallina-extensions + language/coq-library + language/cic + language/module-system + +.. toctree:: + :caption: The proof engine + + proof-engine/vernacular-commands + proof-engine/proof-handling + proof-engine/tactics + proof-engine/ltac + proof-engine/detailed-tactic-examples + proof-engine/ssreflect-proof-language + +.. toctree:: + :caption: User extensions + + user-extensions/syntax-extensions + user-extensions/proof-schemes + +.. toctree:: + :caption: Practical tools + + practical-tools/coq-commands + practical-tools/utilities + practical-tools/coqide + +.. toctree:: + :caption: Addendum + + addendum/extended-pattern-matching + addendum/implicit-coercions + addendum/canonical-structures + addendum/type-classes + addendum/omega + addendum/micromega + addendum/extraction + addendum/program + addendum/ring + addendum/nsatz + addendum/generalized-rewriting + addendum/parallel-proof-processing + addendum/miscellaneous-extensions + addendum/universe-polymorphism + addendum/sprop + +.. toctree:: + :caption: Reference + + zebibliography + +.. include:: license.rst + +.. [#PG] Proof-General is available at https://proofgeneral.github.io/. + Optionally, you can enhance it with the minor mode + Company-Coq :cite:`Pit16` + (see https://github.com/cpitclaudel/company-coq). diff --git a/doc/sphinx/index.latex.rst b/doc/sphinx/index.latex.rst new file mode 100644 index 0000000000..708820fff7 --- /dev/null +++ b/doc/sphinx/index.latex.rst @@ -0,0 +1,89 @@ +========================== + The Coq Reference Manual +========================== + +------------ +Introduction +------------ + +.. include:: introduction.rst + +.. include:: license.rst + +.. [#PG] Proof-General is available at https://proofgeneral.github.io/. + Optionally, you can enhance it with the minor mode + Company-Coq :cite:`Pit16` + (see https://github.com/cpitclaudel/company-coq). + +.. include:: history.rst + +.. include:: changes.rst + +------------ +The language +------------ + +.. toctree:: + + language/gallina-specification-language + language/gallina-extensions + language/coq-library + language/cic + language/module-system + +---------------- +The proof engine +---------------- + +.. toctree:: + + proof-engine/vernacular-commands + proof-engine/proof-handling + proof-engine/tactics + proof-engine/ltac + proof-engine/detailed-tactic-examples + proof-engine/ssreflect-proof-language + +--------------- +User extensions +--------------- + +.. toctree:: + + user-extensions/syntax-extensions + user-extensions/proof-schemes + +--------------- +Practical tools +--------------- + +.. toctree:: + + practical-tools/coq-commands + practical-tools/utilities + practical-tools/coqide + +-------- +Addendum +-------- + +.. toctree:: + + addendum/extended-pattern-matching + addendum/implicit-coercions + addendum/canonical-structures + addendum/type-classes + addendum/omega + addendum/micromega + addendum/extraction + addendum/program + addendum/ring + addendum/nsatz + addendum/generalized-rewriting + addendum/parallel-proof-processing + addendum/miscellaneous-extensions + addendum/universe-polymorphism + addendum/sprop + +.. toctree:: + zebibliography diff --git a/doc/sphinx/introduction.rst b/doc/sphinx/introduction.rst new file mode 100644 index 0000000000..bcdf3277ad --- /dev/null +++ b/doc/sphinx/introduction.rst @@ -0,0 +1,105 @@ +This document is the Reference Manual of the |Coq| proof assistant. +To start using Coq, it is advised to first read a tutorial. +Links to several tutorials can be found at +https://coq.inria.fr/documentation and +https://github.com/coq/coq/wiki#coq-tutorials + +The |Coq| system is designed to develop mathematical proofs, and +especially to write formal specifications, programs and to verify that +programs are correct with respect to their specifications. It provides a +specification language named |Gallina|. Terms of |Gallina| can represent +programs as well as properties of these programs and proofs of these +properties. Using the so-called *Curry-Howard isomorphism*, programs, +properties and proofs are formalized in the same language called +*Calculus of Inductive Constructions*, that is a +:math:`\lambda`-calculus with a rich type system. All logical judgments +in |Coq| are typing judgments. The very heart of the |Coq| system is the +type checking algorithm that checks the correctness of proofs, in other +words that checks that a program complies to its specification. |Coq| also +provides an interactive proof assistant to build proofs using specific +programs called *tactics*. + +All services of the |Coq| proof assistant are accessible by interpretation +of a command language called *the vernacular*. + +Coq has an interactive mode in which commands are interpreted as the +user types them in from the keyboard and a compiled mode where commands +are processed from a file. + +- In interactive mode, users can develop their theories and proofs step by + step, and query the system for available theorems and definitions. The + interactive mode is generally run with the help of an IDE, such + as CoqIDE, documented in :ref:`coqintegrateddevelopmentenvironment`, + Emacs with Proof-General :cite:`Asp00` [#PG]_, + or jsCoq to run Coq in your browser (see https://github.com/ejgallego/jscoq). + The `coqtop` read-eval-print-loop can also be used directly, for debugging + purposes. + +- The compiled mode acts as a proof checker taking a file containing a + whole development in order to ensure its correctness. Moreover, + |Coq|’s compiler provides an output file containing a compact + representation of its input. The compiled mode is run with the `coqc` + command. + +.. seealso:: :ref:`thecoqcommands`. + +How to read this book +--------------------- + +This is a Reference Manual, so it is not intended for continuous reading. +We recommend using the various indexes to quickly locate the documentation +you are looking for. There is a global index, and a number of specific indexes +for tactics, vernacular commands, and error messages and warnings. +Nonetheless, the manual has some structure that is explained below. + +- The first part describes the specification language, |Gallina|. + Chapters :ref:`gallinaspecificationlanguage` and :ref:`extensionsofgallina` describe the concrete + syntax as well as the meaning of programs, theorems and proofs in the + Calculus of Inductive Constructions. Chapter :ref:`thecoqlibrary` describes the + standard library of |Coq|. Chapter :ref:`calculusofinductiveconstructions` is a mathematical description + of the formalism. Chapter :ref:`themodulesystem` describes the module + system. + +- The second part describes the proof engine. It is divided in six + chapters. Chapter :ref:`vernacularcommands` presents all commands (we + call them *vernacular commands*) that are not directly related to + interactive proving: requests to the environment, complete or partial + evaluation, loading and compiling files. How to start and stop + proofs, do multiple proofs in parallel is explained in + Chapter :ref:`proofhandling`. In Chapter :ref:`tactics`, all commands that + realize one or more steps of the proof are presented: we call them + *tactics*. The language to combine these tactics into complex proof + strategies is given in Chapter :ref:`ltac`. Examples of tactics + are described in Chapter :ref:`detailedexamplesoftactics`. + Finally, the |SSR| proof language is presented in + Chapter :ref:`thessreflectprooflanguage`. + +- The third part describes how to extend the syntax of |Coq| in + Chapter :ref:`syntaxextensionsandinterpretationscopes` and how to define + new induction principles in Chapter :ref:`proofschemes`. + +- In the fourth part more practical tools are documented. First in + Chapter :ref:`thecoqcommands`, the usage of `coqc` (batch mode) and + `coqtop` (interactive mode) with their options is described. Then, + in Chapter :ref:`utilities`, various utilities that come with the + |Coq| distribution are presented. Finally, Chapter :ref:`coqintegrateddevelopmentenvironment` + describes CoqIDE. + +- The fifth part documents a number of advanced features, including coercions, + canonical structures, typeclasses, program extraction, and specialized + solvers and tactics. See the table of contents for a complete list. + +List of additional documentation +-------------------------------- + +This manual does not contain all the documentation the user may need +about |Coq|. Various informations can be found in the following documents: + +Installation + A text file `INSTALL` that comes with the sources explains how to + install |Coq|. + +The |Coq| standard library + A commented version of sources of the |Coq| standard library + (including only the specifications, the proofs are removed) is + available at https://coq.inria.fr/stdlib/. diff --git a/doc/sphinx/language/cic.rst b/doc/sphinx/language/cic.rst new file mode 100644 index 0000000000..ef183174d7 --- /dev/null +++ b/doc/sphinx/language/cic.rst @@ -0,0 +1,1937 @@ +.. _calculusofinductiveconstructions: + + +Calculus of Inductive Constructions +==================================== + +The underlying formal language of |Coq| is a *Calculus of Inductive +Constructions* (|Cic|) whose inference rules are presented in this +chapter. The history of this formalism as well as pointers to related +work are provided in a separate chapter; see *Credits*. + + +.. _The-terms: + +The terms +------------- + +The expressions of the |Cic| are *terms* and all terms have a *type*. +There are types for functions (or programs), there are atomic types +(especially datatypes)... but also types for proofs and types for the +types themselves. Especially, any object handled in the formalism must +belong to a type. For instance, universal quantification is relative +to a type and takes the form “*for all x of type* :math:`T`, :math:`P`”. The expression +“:math:`x` *of type* :math:`T`” is written “:math:`x:T`”. Informally, “:math:`x:T`” can be thought as +“:math:`x` *belongs to* :math:`T`”. + +The types of types are *sorts*. Types and sorts are themselves terms +so that terms, types and sorts are all components of a common +syntactic language of terms which is described in Section :ref:`terms` but, +first, we describe sorts. + + +.. _Sorts: + +Sorts +~~~~~~~~~~~ + +All sorts have a type and there is an infinite well-founded typing +hierarchy of sorts whose base sorts are :math:`\SProp`, :math:`\Prop` +and :math:`\Set`. + +The sort :math:`\Prop` intends to be the type of logical propositions. If :math:`M` is a +logical proposition then it denotes the class of terms representing +proofs of :math:`M`. An object :math:`m` belonging to :math:`M` witnesses the fact that :math:`M` is +provable. An object of type :math:`\Prop` is called a proposition. + +The sort :math:`\SProp` is like :math:`\Prop` but the propositions in +:math:`\SProp` are known to have irrelevant proofs (all proofs are +equal). Objects of type :math:`\SProp` are called strict propositions. +:math:`\SProp` is rejected except when using the compiler option +``-allow-sprop``. See :ref:`sprop` for information about using +:math:`\SProp`. + +The sort :math:`\Set` intends to be the type of small sets. This includes data +types such as booleans and naturals, but also products, subsets, and +function types over these data types. + +:math:`\SProp`, :math:`\Prop` and :math:`\Set` themselves can be manipulated as ordinary terms. +Consequently they also have a type. Because assuming simply that :math:`\Set` +has type :math:`\Set` leads to an inconsistent theory :cite:`Coq86`, the language of +|Cic| has infinitely many sorts. There are, in addition to the base sorts, +a hierarchy of universes :math:`\Type(i)` for any integer :math:`i ≥ 1`. + +Like :math:`\Set`, all of the sorts :math:`\Type(i)` contain small sets such as +booleans, natural numbers, as well as products, subsets and function +types over small sets. But, unlike :math:`\Set`, they also contain large sets, +namely the sorts :math:`\Set` and :math:`\Type(j)` for :math:`j<i`, and all products, subsets +and function types over these sorts. + +Formally, we call :math:`\Sort` the set of sorts which is defined by: + +.. math:: + + \Sort \equiv \{\SProp,\Prop,\Set,\Type(i)\;|\; i~∈ ℕ\} + +Their properties, such as: :math:`\Prop:\Type(1)`, :math:`\Set:\Type(1)`, and +:math:`\Type(i):\Type(i+1)`, are defined in Section :ref:`subtyping-rules`. + +The user does not have to mention explicitly the index :math:`i` when +referring to the universe :math:`\Type(i)`. One only writes :math:`\Type`. The system +itself generates for each instance of :math:`\Type` a new index for the +universe and checks that the constraints between these indexes can be +solved. From the user point of view we consequently have :math:`\Type:\Type`. We +shall make precise in the typing rules the constraints between the +indices. + + +.. _Implementation-issues: + +**Implementation issues** In practice, the Type hierarchy is +implemented using *algebraic +universes*. An algebraic universe :math:`u` is either a variable (a qualified +identifier with a number) or a successor of an algebraic universe (an +expression :math:`u+1`), or an upper bound of algebraic universes (an +expression :math:`\max(u_1 ,...,u_n )`), or the base universe (the expression +:math:`0`) which corresponds, in the arity of template polymorphic inductive +types (see Section +:ref:`well-formed-inductive-definitions`), +to the predicative sort :math:`\Set`. A graph of +constraints between the universe variables is maintained globally. To +ensure the existence of a mapping of the universes to the positive +integers, the graph of constraints must remain acyclic. Typing +expressions that violate the acyclicity of the graph of constraints +results in a Universe inconsistency error. + +.. seealso:: Section :ref:`printing-universes`. + + +.. _Terms: + +Terms +~~~~~ + + + +Terms are built from sorts, variables, constants, abstractions, +applications, local definitions, and products. From a syntactic point +of view, types cannot be distinguished from terms, except that they +cannot start by an abstraction or a constructor. More precisely the +language of the *Calculus of Inductive Constructions* is built from +the following rules. + + +#. the sorts :math:`\SProp`, :math:`\Prop`, :math:`\Set`, :math:`\Type(i)` are terms. +#. variables, hereafter ranged over by letters :math:`x`, :math:`y`, etc., are terms +#. constants, hereafter ranged over by letters :math:`c`, :math:`d`, etc., are terms. +#. if :math:`x` is a variable and :math:`T`, :math:`U` are terms then + :math:`∀ x:T,~U` (:g:`forall x:T, U` in |Coq| concrete syntax) is a term. + If :math:`x` occurs in :math:`U`, :math:`∀ x:T,~U` reads as + “for all :math:`x` of type :math:`T`, :math:`U`”. + As :math:`U` depends on :math:`x`, one says that :math:`∀ x:T,~U` is + a *dependent product*. If :math:`x` does not occur in :math:`U` then + :math:`∀ x:T,~U` reads as + “if :math:`T` then :math:`U`”. A *non dependent product* can be + written: :math:`T \rightarrow U`. +#. if :math:`x` is a variable and :math:`T`, :math:`u` are terms then + :math:`λ x:T .~u` (:g:`fun x:T => u` + in |Coq| concrete syntax) is a term. This is a notation for the + λ-abstraction of λ-calculus :cite:`Bar81`. The term :math:`λ x:T .~u` is a function + which maps elements of :math:`T` to the expression :math:`u`. +#. if :math:`t` and :math:`u` are terms then :math:`(t~u)` is a term + (:g:`t u` in |Coq| concrete + syntax). The term :math:`(t~u)` reads as “:math:`t` applied to :math:`u`”. +#. if :math:`x` is a variable, and :math:`t`, :math:`T` and :math:`u` are + terms then :math:`\letin{x}{t:T}{u}` is + a term which denotes the term :math:`u` where the variable :math:`x` is locally bound + to :math:`t` of type :math:`T`. This stands for the common “let-in” construction of + functional programs such as ML or Scheme. + + + +.. _Free-variables: + +**Free variables.** +The notion of free variables is defined as usual. In the expressions +:math:`λx:T.~U` and :math:`∀ x:T,~U` the occurrences of :math:`x` in :math:`U` are bound. + + +.. _Substitution: + +**Substitution.** +The notion of substituting a term :math:`t` to free occurrences of a variable +:math:`x` in a term :math:`u` is defined as usual. The resulting term is written +:math:`\subst{u}{x}{t}`. + + +.. _The-logical-vs-programming-readings: + +**The logical vs programming readings.** +The constructions of the |Cic| can be used to express both logical and +programming notions, accordingly to the Curry-Howard correspondence +between proofs and programs, and between propositions and types +:cite:`Cur58,How80,Bru72`. + +For instance, let us assume that :math:`\nat` is the type of natural numbers +with zero element written :math:`0` and that :g:`True` is the always true +proposition. Then :math:`→` is used both to denote :math:`\nat→\nat` which is the type +of functions from :math:`\nat` to :math:`\nat`, to denote True→True which is an +implicative proposition, to denote :math:`\nat →\Prop` which is the type of +unary predicates over the natural numbers, etc. + +Let us assume that ``mult`` is a function of type :math:`\nat→\nat→\nat` and ``eqnat`` a +predicate of type :math:`\nat→\nat→ \Prop`. The λ-abstraction can serve to build +“ordinary” functions as in :math:`λ x:\nat.~(\kw{mult}~x~x)` (i.e. +:g:`fun x:nat => mult x x` +in |Coq| notation) but may build also predicates over the natural +numbers. For instance :math:`λ x:\nat.~(\kw{eqnat}~x~0)` +(i.e. :g:`fun x:nat => eqnat x 0` +in |Coq| notation) will represent the predicate of one variable :math:`x` which +asserts the equality of :math:`x` with :math:`0`. This predicate has type +:math:`\nat → \Prop` +and it can be applied to any expression of type :math:`\nat`, say :math:`t`, to give an +object :math:`P~t` of type :math:`\Prop`, namely a proposition. + +Furthermore :g:`forall x:nat, P x` will represent the type of functions +which associate to each natural number :math:`n` an object of type :math:`(P~n)` and +consequently represent the type of proofs of the formula “:math:`∀ x.~P(x)`”. + + +.. _Typing-rules: + +Typing rules +---------------- + +As objects of type theory, terms are subjected to *type discipline*. +The well typing of a term depends on a global environment and a local +context. + + +.. _Local-context: + +**Local context.** +A *local context* is an ordered list of *local declarations* of names +which we call *variables*. The declaration of some variable :math:`x` is +either a *local assumption*, written :math:`x:T` (:math:`T` is a type) or a *local +definition*, written :math:`x:=t:T`. We use brackets to write local contexts. +A typical example is :math:`[x:T;~y:=u:U;~z:V]`. Notice that the variables +declared in a local context must be distinct. If :math:`Γ` is a local context +that declares some :math:`x`, we +write :math:`x ∈ Γ`. By writing :math:`(x:T) ∈ Γ` we mean that either :math:`x:T` is an +assumption in :math:`Γ` or that there exists some :math:`t` such that :math:`x:=t:T` is a +definition in :math:`Γ`. If :math:`Γ` defines some :math:`x:=t:T`, we also write :math:`(x:=t:T) ∈ Γ`. +For the rest of the chapter, :math:`Γ::(y:T)` denotes the local context :math:`Γ` +enriched with the local assumption :math:`y:T`. Similarly, :math:`Γ::(y:=t:T)` denotes +the local context :math:`Γ` enriched with the local definition :math:`(y:=t:T)`. The +notation :math:`[]` denotes the empty local context. By :math:`Γ_1 ; Γ_2` we mean +concatenation of the local context :math:`Γ_1` and the local context :math:`Γ_2`. + + +.. _Global-environment: + +**Global environment.** +A *global environment* is an ordered list of *global declarations*. +Global declarations are either *global assumptions* or *global +definitions*, but also declarations of inductive objects. Inductive +objects themselves declare both inductive or coinductive types and +constructors (see Section :ref:`inductive-definitions`). + +A *global assumption* will be represented in the global environment as +:math:`(c:T)` which assumes the name :math:`c` to be of some type :math:`T`. A *global +definition* will be represented in the global environment as :math:`c:=t:T` +which defines the name :math:`c` to have value :math:`t` and type :math:`T`. We shall call +such names *constants*. For the rest of the chapter, the :math:`E;~c:T` denotes +the global environment :math:`E` enriched with the global assumption :math:`c:T`. +Similarly, :math:`E;~c:=t:T` denotes the global environment :math:`E` enriched with the +global definition :math:`(c:=t:T)`. + +The rules for inductive definitions (see Section +:ref:`inductive-definitions`) have to be considered as assumption +rules to which the following definitions apply: if the name :math:`c` +is declared in :math:`E`, we write :math:`c ∈ E` and if :math:`c:T` or +:math:`c:=t:T` is declared in :math:`E`, we write :math:`(c : T) ∈ E`. + + +.. _Typing-rules2: + +**Typing rules.** +In the following, we define simultaneously two judgments. The first +one :math:`\WTEG{t}{T}` means the term :math:`t` is well-typed and has type :math:`T` in the +global environment :math:`E` and local context :math:`Γ`. The second judgment :math:`\WFE{Γ}` +means that the global environment :math:`E` is well-formed and the local +context :math:`Γ` is a valid local context in this global environment. + +A term :math:`t` is well typed in a global environment :math:`E` iff +there exists a local context :math:`\Gamma` and a term :math:`T` such +that the judgment :math:`\WTEG{t}{T}` can be derived from the +following rules. + +.. inference:: W-Empty + + --------- + \WF{[]}{} + +.. inference:: W-Local-Assum + + \WTEG{T}{s} + s \in \Sort + x \not\in \Gamma % \cup E + ------------------------- + \WFE{\Gamma::(x:T)} + +.. inference:: W-Local-Def + + \WTEG{t}{T} + x \not\in \Gamma % \cup E + ------------------------- + \WFE{\Gamma::(x:=t:T)} + +.. inference:: W-Global-Assum + + \WTE{}{T}{s} + s \in \Sort + c \notin E + ------------ + \WF{E;~c:T}{} + +.. inference:: W-Global-Def + + \WTE{}{t}{T} + c \notin E + --------------- + \WF{E;~c:=t:T}{} + +.. inference:: Ax-SProp + + \WFE{\Gamma} + ---------------------- + \WTEG{\SProp}{\Type(1)} + +.. inference:: Ax-Prop + + \WFE{\Gamma} + ---------------------- + \WTEG{\Prop}{\Type(1)} + +.. inference:: Ax-Set + + \WFE{\Gamma} + --------------------- + \WTEG{\Set}{\Type(1)} + +.. inference:: Ax-Type + + \WFE{\Gamma} + --------------------------- + \WTEG{\Type(i)}{\Type(i+1)} + +.. inference:: Var + + \WFE{\Gamma} + (x:T) \in \Gamma~~\mbox{or}~~(x:=t:T) \in \Gamma~\mbox{for some $t$} + -------------------------------------------------------------------- + \WTEG{x}{T} + +.. inference:: Const + + \WFE{\Gamma} + (c:T) \in E~~\mbox{or}~~(c:=t:T) \in E~\mbox{for some $t$} + ---------------------------------------------------------- + \WTEG{c}{T} + +.. inference:: Prod-SProp + + \WTEG{T}{s} + s \in {\Sort} + \WTE{\Gamma::(x:T)}{U}{\SProp} + ----------------------------- + \WTEG{\forall~x:T,U}{\SProp} + +.. inference:: Prod-Prop + + \WTEG{T}{s} + s \in \Sort + \WTE{\Gamma::(x:T)}{U}{\Prop} + ----------------------------- + \WTEG{∀ x:T,~U}{\Prop} + +.. inference:: Prod-Set + + \WTEG{T}{s} + s \in \{\SProp, \Prop, \Set\} + \WTE{\Gamma::(x:T)}{U}{\Set} + ---------------------------- + \WTEG{∀ x:T,~U}{\Set} + +.. inference:: Prod-Type + + \WTEG{T}{s} + s \in \{\SProp, \Type{i}\} + \WTE{\Gamma::(x:T)}{U}{\Type(i)} + -------------------------------- + \WTEG{∀ x:T,~U}{\Type(i)} + +.. inference:: Lam + + \WTEG{∀ x:T,~U}{s} + \WTE{\Gamma::(x:T)}{t}{U} + ------------------------------------ + \WTEG{λ x:T\mto t}{∀ x:T,~U} + +.. inference:: App + + \WTEG{t}{∀ x:U,~T} + \WTEG{u}{U} + ------------------------------ + \WTEG{(t\ u)}{\subst{T}{x}{u}} + +.. inference:: Let + + \WTEG{t}{T} + \WTE{\Gamma::(x:=t:T)}{u}{U} + ----------------------------------------- + \WTEG{\letin{x}{t:T}{u}}{\subst{U}{x}{t}} + + + +.. note:: + + **Prod-Prop** and **Prod-Set** typing-rules make sense if we consider the + semantic difference between :math:`\Prop` and :math:`\Set`: + + + All values of a type that has a sort :math:`\Set` are extractable. + + No values of a type that has a sort :math:`\Prop` are extractable. + + + +.. note:: + We may have :math:`\letin{x}{t:T}{u}` well-typed without having + :math:`((λ x:T.~u)~t)` well-typed (where :math:`T` is a type of + :math:`t`). This is because the value :math:`t` associated to + :math:`x` may be used in a conversion rule + (see Section :ref:`Conversion-rules`). + + +.. _Conversion-rules: + +Conversion rules +-------------------- + +In |Cic|, there is an internal reduction mechanism. In particular, it +can decide if two programs are *intentionally* equal (one says +*convertible*). Convertibility is described in this section. + + +.. _beta-reduction: + +β-reduction +~~~~~~~~~~~ + +We want to be able to identify some terms as we can identify the +application of a function to a given argument with its result. For +instance the identity function over a given type :math:`T` can be written +:math:`λx:T.~x`. In any global environment :math:`E` and local context +:math:`Γ`, we want to identify any object :math:`a` (of type +:math:`T`) with the application :math:`((λ x:T.~x)~a)`. We define for +this a *reduction* (or a *conversion*) rule we call :math:`β`: + +.. math:: + + E[Γ] ⊢ ((λx:T.~t)~u)~\triangleright_β~\subst{t}{x}{u} + +We say that :math:`\subst{t}{x}{u}` is the *β-contraction* of +:math:`((λx:T.~t)~u)` and, conversely, that :math:`((λ x:T.~t)~u)` is the +*β-expansion* of :math:`\subst{t}{x}{u}`. + +According to β-reduction, terms of the *Calculus of Inductive +Constructions* enjoy some fundamental properties such as confluence, +strong normalization, subject reduction. These results are +theoretically of great importance but we will not detail them here and +refer the interested reader to :cite:`Coq85`. + + +.. _iota-reduction: + +ι-reduction +~~~~~~~~~~~ + +A specific conversion rule is associated to the inductive objects in +the global environment. We shall give later on (see Section +:ref:`Well-formed-inductive-definitions`) the precise rules but it +just says that a destructor applied to an object built from a +constructor behaves as expected. This reduction is called ι-reduction +and is more precisely studied in :cite:`Moh93,Wer94`. + + +.. _delta-reduction: + +δ-reduction +~~~~~~~~~~~ + +We may have variables defined in local contexts or constants defined +in the global environment. It is legal to identify such a reference +with its value, that is to expand (or unfold) it into its value. This +reduction is called δ-reduction and shows as follows. + +.. inference:: Delta-Local + + \WFE{\Gamma} + (x:=t:T) ∈ Γ + -------------- + E[Γ] ⊢ x~\triangleright_Δ~t + +.. inference:: Delta-Global + + \WFE{\Gamma} + (c:=t:T) ∈ E + -------------- + E[Γ] ⊢ c~\triangleright_δ~t + + +.. _zeta-reduction: + +ζ-reduction +~~~~~~~~~~~ + +|Coq| allows also to remove local definitions occurring in terms by +replacing the defined variable by its value. The declaration being +destroyed, this reduction differs from δ-reduction. It is called +ζ-reduction and shows as follows. + +.. inference:: Zeta + + \WFE{\Gamma} + \WTEG{u}{U} + \WTE{\Gamma::(x:=u:U)}{t}{T} + -------------- + E[Γ] ⊢ \letin{x}{u:U}{t}~\triangleright_ζ~\subst{t}{x}{u} + + +.. _eta-expansion: + +η-expansion +~~~~~~~~~~~ + +Another important concept is η-expansion. It is legal to identify any +term :math:`t` of functional type :math:`∀ x:T,~U` with its so-called η-expansion + +.. math:: + λx:T.~(t~x) + +for :math:`x` an arbitrary variable name fresh in :math:`t`. + + +.. note:: + + We deliberately do not define η-reduction: + + .. math:: + λ x:T.~(t~x)~\not\triangleright_η~t + + This is because, in general, the type of :math:`t` need not to be convertible + to the type of :math:`λ x:T.~(t~x)`. E.g., if we take :math:`f` such that: + + .. math:: + f ~:~ ∀ x:\Type(2),~\Type(1) + + then + + .. math:: + λ x:\Type(1).~(f~x) ~:~ ∀ x:\Type(1),~\Type(1) + + We could not allow + + .. math:: + λ x:\Type(1).~(f~x) ~\triangleright_η~ f + + because the type of the reduced term :math:`∀ x:\Type(2),~\Type(1)` would not be + convertible to the type of the original term :math:`∀ x:\Type(1),~\Type(1)`. + +.. _proof-irrelevance: + +Proof Irrelevance +~~~~~~~~~~~~~~~~~ + +It is legal to identify any two terms whose common type is a strict +proposition :math:`A : \SProp`. Terms in a strict propositions are +therefore called *irrelevant*. + +.. _convertibility: + +Convertibility +~~~~~~~~~~~~~~ + +Let us write :math:`E[Γ] ⊢ t \triangleright u` for the contextual closure of the +relation :math:`t` reduces to :math:`u` in the global environment +:math:`E` and local context :math:`Γ` with one of the previous +reductions β, δ, ι or ζ. + +We say that two terms :math:`t_1` and :math:`t_2` are +*βδιζη-convertible*, or simply *convertible*, or *equivalent*, in the +global environment :math:`E` and local context :math:`Γ` iff there +exist terms :math:`u_1` and :math:`u_2` such that :math:`E[Γ] ⊢ t_1 \triangleright +… \triangleright u_1` and :math:`E[Γ] ⊢ t_2 \triangleright … \triangleright u_2` and either :math:`u_1` and +:math:`u_2` are identical up to irrelevant subterms, or they are convertible up to η-expansion, +i.e. :math:`u_1` is :math:`λ x:T.~u_1'` and :math:`u_2 x` is +recursively convertible to :math:`u_1'`, or, symmetrically, +:math:`u_2` is :math:`λx:T.~u_2'` +and :math:`u_1 x` is recursively convertible to :math:`u_2'`. We then write +:math:`E[Γ] ⊢ t_1 =_{βδιζη} t_2`. + +Apart from this we consider two instances of polymorphic and +cumulative (see Chapter :ref:`polymorphicuniverses`) inductive types +(see below) convertible + +.. math:: + E[Γ] ⊢ t~w_1 … w_m =_{βδιζη} t~w_1' … w_m' + +if we have subtypings (see below) in both directions, i.e., + +.. math:: + E[Γ] ⊢ t~w_1 … w_m ≤_{βδιζη} t~w_1' … w_m' + +and + +.. math:: + E[Γ] ⊢ t~w_1' … w_m' ≤_{βδιζη} t~w_1 … w_m. + +Furthermore, we consider + +.. math:: + E[Γ] ⊢ c~v_1 … v_m =_{βδιζη} c'~v_1' … v_m' + +convertible if + +.. math:: + E[Γ] ⊢ v_i =_{βδιζη} v_i' + +and we have that :math:`c` and :math:`c'` +are the same constructors of different instances of the same inductive +types (differing only in universe levels) such that + +.. math:: + E[Γ] ⊢ c~v_1 … v_m : t~w_1 … w_m + +and + +.. math:: + E[Γ] ⊢ c'~v_1' … v_m' : t'~ w_1' … w_m ' + +and we have + +.. math:: + E[Γ] ⊢ t~w_1 … w_m =_{βδιζη} t~w_1' … w_m'. + +The convertibility relation allows introducing a new typing rule which +says that two convertible well-formed types have the same inhabitants. + + +.. _subtyping-rules: + +Subtyping rules +------------------- + +At the moment, we did not take into account one rule between universes +which says that any term in a universe of index :math:`i` is also a term in +the universe of index :math:`i+1` (this is the *cumulativity* rule of |Cic|). +This property extends the equivalence relation of convertibility into +a *subtyping* relation inductively defined by: + + +#. if :math:`E[Γ] ⊢ t =_{βδιζη} u` then :math:`E[Γ] ⊢ t ≤_{βδιζη} u`, +#. if :math:`i ≤ j` then :math:`E[Γ] ⊢ \Type(i) ≤_{βδιζη} \Type(j)`, +#. for any :math:`i`, :math:`E[Γ] ⊢ \Set ≤_{βδιζη} \Type(i)`, +#. :math:`E[Γ] ⊢ \Prop ≤_{βδιζη} \Set`, hence, by transitivity, + :math:`E[Γ] ⊢ \Prop ≤_{βδιζη} \Type(i)`, for any :math:`i` + (note: :math:`\SProp` is not related by cumulativity to any other term) +#. if :math:`E[Γ] ⊢ T =_{βδιζη} U` and + :math:`E[Γ::(x:T)] ⊢ T' ≤_{βδιζη} U'` then + :math:`E[Γ] ⊢ ∀x:T,~T′ ≤_{βδιζη} ∀ x:U,~U′`. +#. if :math:`\ind{p}{Γ_I}{Γ_C}` is a universe polymorphic and cumulative + (see Chapter :ref:`polymorphicuniverses`) inductive type (see below) + and + :math:`(t : ∀Γ_P ,∀Γ_{\mathit{Arr}(t)}, S)∈Γ_I` + and + :math:`(t' : ∀Γ_P' ,∀Γ_{\mathit{Arr}(t)}', S')∈Γ_I` + are two different instances of *the same* inductive type (differing only in + universe levels) with constructors + + .. math:: + [c_1 : ∀Γ_P ,∀ T_{1,1} … T_{1,n_1} ,~t~v_{1,1} … v_{1,m} ;~…;~ + c_k : ∀Γ_P ,∀ T_{k,1} … T_{k,n_k} ,~t~v_{k,1} … v_{k,m} ] + + and + + .. math:: + [c_1 : ∀Γ_P' ,∀ T_{1,1}' … T_{1,n_1}' ,~t'~v_{1,1}' … v_{1,m}' ;~…;~ + c_k : ∀Γ_P' ,∀ T_{k,1}' … T_{k,n_k}' ,~t'~v_{k,1}' … v_{k,m}' ] + + respectively then + + .. math:: + E[Γ] ⊢ t~w_1 … w_m ≤_{βδιζη} t'~w_1' … w_m' + + (notice that :math:`t` and :math:`t'` are both + fully applied, i.e., they have a sort as a type) if + + .. math:: + E[Γ] ⊢ w_i =_{βδιζη} w_i' + + for :math:`1 ≤ i ≤ m` and we have + + + .. math:: + E[Γ] ⊢ T_{i,j} ≤_{βδιζη} T_{i,j}' + + and + + .. math:: + E[Γ] ⊢ A_i ≤_{βδιζη} A_i' + + where :math:`Γ_{\mathit{Arr}(t)} = [a_1 : A_1 ;~ … ;~a_l : A_l ]` and + :math:`Γ_{\mathit{Arr}(t)}' = [a_1 : A_1';~ … ;~a_l : A_l']`. + + +The conversion rule up to subtyping is now exactly: + +.. inference:: Conv + + E[Γ] ⊢ U : s + E[Γ] ⊢ t : T + E[Γ] ⊢ T ≤_{βδιζη} U + -------------- + E[Γ] ⊢ t : U + + +.. _Normal-form: + +**Normal form**. A term which cannot be any more reduced is said to be in *normal +form*. There are several ways (or strategies) to apply the reduction +rules. Among them, we have to mention the *head reduction* which will +play an important role (see Chapter :ref:`tactics`). Any term :math:`t` can be written as +:math:`λ x_1 :T_1 .~… λ x_k :T_k .~(t_0~t_1 … t_n )` where :math:`t_0` is not an +application. We say then that :math:`t_0` is the *head of* :math:`t`. If we assume +that :math:`t_0` is :math:`λ x:T.~u_0` then one step of β-head reduction of :math:`t` is: + +.. math:: + λ x_1 :T_1 .~… λ x_k :T_k .~(λ x:T.~u_0~t_1 … t_n ) ~\triangleright~ + λ (x_1 :T_1 )…(x_k :T_k ).~(\subst{u_0}{x}{t_1}~t_2 … t_n ) + +Iterating the process of head reduction until the head of the reduced +term is no more an abstraction leads to the *β-head normal form* of :math:`t`: + +.. math:: + t \triangleright … \triangleright λ x_1 :T_1 .~…λ x_k :T_k .~(v~u_1 … u_m ) + +where :math:`v` is not an abstraction (nor an application). Note that the head +normal form must not be confused with the normal form since some :math:`u_i` +can be reducible. Similar notions of head-normal forms involving δ, ι +and ζ reductions or any combination of those can also be defined. + + +.. _inductive-definitions: + +Inductive Definitions +------------------------- + +Formally, we can represent any *inductive definition* as +:math:`\ind{p}{Γ_I}{Γ_C}` where: + ++ :math:`Γ_I` determines the names and types of inductive types; ++ :math:`Γ_C` determines the names and types of constructors of these + inductive types; ++ :math:`p` determines the number of parameters of these inductive types. + + +These inductive definitions, together with global assumptions and +global definitions, then form the global environment. Additionally, +for any :math:`p` there always exists :math:`Γ_P =[a_1 :A_1 ;~…;~a_p :A_p ]` such that +each :math:`T` in :math:`(t:T)∈Γ_I \cup Γ_C` can be written as: :math:`∀Γ_P , T'` where :math:`Γ_P` is +called the *context of parameters*. Furthermore, we must have that +each :math:`T` in :math:`(t:T)∈Γ_I` can be written as: :math:`∀Γ_P,∀Γ_{\mathit{Arr}(t)}, S` where +:math:`Γ_{\mathit{Arr}(t)}` is called the *Arity* of the inductive type :math:`t` and :math:`S` is called +the sort of the inductive type :math:`t` (not to be confused with :math:`\Sort` which is the set of sorts). + +.. example:: + + The declaration for parameterized lists is: + + .. math:: + \ind{1}{[\List:\Set→\Set]}{\left[\begin{array}{rcl} + \Nil & : & ∀ A:\Set,~\List~A \\ + \cons & : & ∀ A:\Set,~A→ \List~A→ \List~A + \end{array} + \right]} + + which corresponds to the result of the |Coq| declaration: + + .. coqtop:: in + + Inductive list (A:Set) : Set := + | nil : list A + | cons : A -> list A -> list A. + +.. example:: + + The declaration for a mutual inductive definition of tree and forest + is: + + .. math:: + \ind{0}{\left[\begin{array}{rcl}\tree&:&\Set\\\forest&:&\Set\end{array}\right]} + {\left[\begin{array}{rcl} + \node &:& \forest → \tree\\ + \emptyf &:& \forest\\ + \consf &:& \tree → \forest → \forest\\ + \end{array}\right]} + + which corresponds to the result of the |Coq| declaration: + + .. coqtop:: in + + Inductive tree : Set := + | node : forest -> tree + with forest : Set := + | emptyf : forest + | consf : tree -> forest -> forest. + +.. example:: + + The declaration for a mutual inductive definition of even and odd is: + + .. math:: + \ind{0}{\left[\begin{array}{rcl}\even&:&\nat → \Prop \\ + \odd&:&\nat → \Prop \end{array}\right]} + {\left[\begin{array}{rcl} + \evenO &:& \even~0\\ + \evenS &:& ∀ n,~\odd~n → \even~(\nS~n)\\ + \oddS &:& ∀ n,~\even~n → \odd~(\nS~n) + \end{array}\right]} + + which corresponds to the result of the |Coq| declaration: + + .. coqtop:: in + + Inductive even : nat -> Prop := + | even_O : even 0 + | even_S : forall n, odd n -> even (S n) + with odd : nat -> Prop := + | odd_S : forall n, even n -> odd (S n). + + + +.. _Types-of-inductive-objects: + +Types of inductive objects +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +We have to give the type of constants in a global environment :math:`E` which +contains an inductive definition. + +.. inference:: Ind + + \WFE{Γ} + \ind{p}{Γ_I}{Γ_C} ∈ E + (a:A)∈Γ_I + --------------------- + E[Γ] ⊢ a : A + +.. inference:: Constr + + \WFE{Γ} + \ind{p}{Γ_I}{Γ_C} ∈ E + (c:C)∈Γ_C + --------------------- + E[Γ] ⊢ c : C + +.. example:: + + Provided that our environment :math:`E` contains inductive definitions we showed before, + these two inference rules above enable us to conclude that: + + .. math:: + \begin{array}{l} + E[Γ] ⊢ \even : \nat→\Prop\\ + E[Γ] ⊢ \odd : \nat→\Prop\\ + E[Γ] ⊢ \evenO : \even~\nO\\ + E[Γ] ⊢ \evenS : ∀ n:\nat,~\odd~n → \even~(\nS~n)\\ + E[Γ] ⊢ \oddS : ∀ n:\nat,~\even~n → \odd~(\nS~n) + \end{array} + + + + +.. _Well-formed-inductive-definitions: + +Well-formed inductive definitions +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +We cannot accept any inductive definition because some of them lead +to inconsistent systems. We restrict ourselves to definitions which +satisfy a syntactic criterion of positivity. Before giving the formal +rules, we need a few definitions: + +Arity of a given sort ++++++++++++++++++++++ + +A type :math:`T` is an *arity of sort* :math:`s` if it converts to the sort :math:`s` or to a +product :math:`∀ x:T,~U` with :math:`U` an arity of sort :math:`s`. + +.. example:: + + :math:`A→\Set` is an arity of sort :math:`\Set`. :math:`∀ A:\Prop,~A→ \Prop` is an arity of sort + :math:`\Prop`. + + +Arity ++++++ +A type :math:`T` is an *arity* if there is a :math:`s∈ \Sort` such that :math:`T` is an arity of +sort :math:`s`. + + +.. example:: + + :math:`A→ \Set` and :math:`∀ A:\Prop,~A→ \Prop` are arities. + + +Type of constructor ++++++++++++++++++++ +We say that :math:`T` is a *type of constructor of* :math:`I` in one of the following +two cases: + ++ :math:`T` is :math:`(I~t_1 … t_n )` ++ :math:`T` is :math:`∀ x:U,~T'` where :math:`T'` is also a type of constructor of :math:`I` + +.. example:: + + :math:`\nat` and :math:`\nat→\nat` are types of constructor of :math:`\nat`. + :math:`∀ A:\Type,~\List~A` and :math:`∀ A:\Type,~A→\List~A→\List~A` are types of constructor of :math:`\List`. + +.. _positivity: + +Positivity Condition +++++++++++++++++++++ + +The type of constructor :math:`T` will be said to *satisfy the positivity +condition* for a constant :math:`X` in the following cases: + ++ :math:`T=(X~t_1 … t_n )` and :math:`X` does not occur free in any :math:`t_i` ++ :math:`T=∀ x:U,~V` and :math:`X` occurs only strictly positively in :math:`U` and the type :math:`V` + satisfies the positivity condition for :math:`X`. + +Strict positivity ++++++++++++++++++ + +The constant :math:`X` *occurs strictly positively* in :math:`T` in the following +cases: + + ++ :math:`X` does not occur in :math:`T` ++ :math:`T` converts to :math:`(X~t_1 … t_n )` and :math:`X` does not occur in any of :math:`t_i` ++ :math:`T` converts to :math:`∀ x:U,~V` and :math:`X` does not occur in type :math:`U` but occurs + strictly positively in type :math:`V` ++ :math:`T` converts to :math:`(I~a_1 … a_m~t_1 … t_p )` where :math:`I` is the name of an + inductive definition of the form + + .. math:: + \ind{m}{I:A}{c_1 :∀ p_1 :P_1 ,… ∀p_m :P_m ,~C_1 ;~…;~c_n :∀ p_1 :P_1 ,… ∀p_m :P_m ,~C_n} + + (in particular, it is + not mutually defined and it has :math:`m` parameters) and :math:`X` does not occur in + any of the :math:`t_i`, and the (instantiated) types of constructor + :math:`\subst{C_i}{p_j}{a_j}_{j=1… m}` of :math:`I` satisfy the nested positivity condition for :math:`X` + +Nested Positivity ++++++++++++++++++ + +The type of constructor :math:`T` of :math:`I` *satisfies the nested positivity +condition* for a constant :math:`X` in the following cases: + ++ :math:`T=(I~b_1 … b_m~u_1 … u_p)`, :math:`I` is an inductive type with :math:`m` + parameters and :math:`X` does not occur in any :math:`u_i` ++ :math:`T=∀ x:U,~V` and :math:`X` occurs only strictly positively in :math:`U` and the type :math:`V` + satisfies the nested positivity condition for :math:`X` + + +.. example:: + + For instance, if one considers the following variant of a tree type + branching over the natural numbers: + + .. coqtop:: in + + Inductive nattree (A:Type) : Type := + | leaf : nattree A + | natnode : A -> (nat -> nattree A) -> nattree A. + + Then every instantiated constructor of ``nattree A`` satisfies the nested positivity + condition for ``nattree``: + + + Type ``nattree A`` of constructor ``leaf`` satisfies the positivity condition for + ``nattree`` because ``nattree`` does not appear in any (real) arguments of the + type of that constructor (primarily because ``nattree`` does not have any (real) + arguments) ... (bullet 1) + + + Type ``A → (nat → nattree A) → nattree A`` of constructor ``natnode`` satisfies the + positivity condition for ``nattree`` because: + + - ``nattree`` occurs only strictly positively in ``A`` ... (bullet 1) + + - ``nattree`` occurs only strictly positively in ``nat → nattree A`` ... (bullet 3 + 2) + + - ``nattree`` satisfies the positivity condition for ``nattree A`` ... (bullet 1) + +.. _Correctness-rules: + +Correctness rules ++++++++++++++++++ + +We shall now describe the rules allowing the introduction of a new +inductive definition. + +Let :math:`E` be a global environment and :math:`Γ_P`, :math:`Γ_I`, :math:`Γ_C` be contexts +such that :math:`Γ_I` is :math:`[I_1 :∀ Γ_P ,A_1 ;~…;~I_k :∀ Γ_P ,A_k]`, and +:math:`Γ_C` is :math:`[c_1:∀ Γ_P ,C_1 ;~…;~c_n :∀ Γ_P ,C_n ]`. Then + +.. inference:: W-Ind + + \WFE{Γ_P} + (E[Γ_I ;Γ_P ] ⊢ C_i : s_{q_i} )_{i=1… n} + ------------------------------------------ + \WF{E;~\ind{p}{Γ_I}{Γ_C}}{} + + +provided that the following side conditions hold: + + + :math:`k>0` and all of :math:`I_j` and :math:`c_i` are distinct names for :math:`j=1… k` and :math:`i=1… n`, + + :math:`p` is the number of parameters of :math:`\ind{p}{Γ_I}{Γ_C}` and :math:`Γ_P` is the + context of parameters, + + for :math:`j=1… k` we have that :math:`A_j` is an arity of sort :math:`s_j` and :math:`I_j ∉ E`, + + for :math:`i=1… n` we have that :math:`C_i` is a type of constructor of :math:`I_{q_i}` which + satisfies the positivity condition for :math:`I_1 … I_k` and :math:`c_i ∉ E`. + +One can remark that there is a constraint between the sort of the +arity of the inductive type and the sort of the type of its +constructors which will always be satisfied for the impredicative +sorts :math:`\SProp` and :math:`\Prop` but may fail to define +inductive type on sort :math:`\Set` and generate constraints +between universes for inductive types in the Type hierarchy. + + +.. example:: + + It is well known that the existential quantifier can be encoded as an + inductive definition. The following declaration introduces the + second-order existential quantifier :math:`∃ X.P(X)`. + + .. coqtop:: in + + Inductive exProp (P:Prop->Prop) : Prop := + | exP_intro : forall X:Prop, P X -> exProp P. + + The same definition on :math:`\Set` is not allowed and fails: + + .. coqtop:: all + + Fail Inductive exSet (P:Set->Prop) : Set := + exS_intro : forall X:Set, P X -> exSet P. + + It is possible to declare the same inductive definition in the + universe :math:`\Type`. The :g:`exType` inductive definition has type + :math:`(\Type(i)→\Prop)→\Type(j)` with the constraint that the parameter :math:`X` of :math:`\kw{exT}_{\kw{intro}}` + has type :math:`\Type(k)` with :math:`k<j` and :math:`k≤ i`. + + .. coqtop:: all + + Inductive exType (P:Type->Prop) : Type := + exT_intro : forall X:Type, P X -> exType P. + + + +.. _Template-polymorphism: + +Template polymorphism ++++++++++++++++++++++ + +Inductive types can be made polymorphic over their arguments +in :math:`\Type`. + +.. flag:: Auto Template Polymorphism + + This option, enabled by default, makes every inductive type declared + at level :math:`\Type` (without annotations or hiding it behind a + definition) template polymorphic. + + This can be prevented using the ``notemplate`` attribute. + + An inductive type can be forced to be template polymorphic using the + ``template`` attribute. + + Template polymorphism and universe polymorphism (see Chapter + :ref:`polymorphicuniverses`) are incompatible, so if the later is + enabled it will prevail over automatic template polymorphism and + cause an error when using the ``template`` attribute. + +.. warn:: Automatically declaring @ident as template polymorphic. + + Warning ``auto-template`` can be used to find which types are + implicitly declared template polymorphic by :flag:`Auto Template + Polymorphism`. + +If :math:`A` is an arity of some sort and :math:`s` is a sort, we write :math:`A_{/s}` +for the arity obtained from :math:`A` by replacing its sort with :math:`s`. +Especially, if :math:`A` is well-typed in some global environment and local +context, then :math:`A_{/s}` is typable by typability of all products in the +Calculus of Inductive Constructions. The following typing rule is +added to the theory. + +Let :math:`\ind{p}{Γ_I}{Γ_C}` be an inductive definition. Let +:math:`Γ_P = [p_1 :P_1 ;~…;~p_p :P_p ]` be its context of parameters, +:math:`Γ_I = [I_1:∀ Γ_P ,A_1 ;~…;~I_k :∀ Γ_P ,A_k ]` its context of definitions and +:math:`Γ_C = [c_1 :∀ Γ_P ,C_1 ;~…;~c_n :∀ Γ_P ,C_n]` its context of constructors, +with :math:`c_i` a constructor of :math:`I_{q_i}`. Let :math:`m ≤ p` be the length of the +longest prefix of parameters such that the :math:`m` first arguments of all +occurrences of all :math:`I_j` in all :math:`C_k` (even the occurrences in the +hypotheses of :math:`C_k`) are exactly applied to :math:`p_1 … p_m` (:math:`m` is the number +of *recursively uniform parameters* and the :math:`p−m` remaining parameters +are the *recursively non-uniform parameters*). Let :math:`q_1 , …, q_r`, with +:math:`0≤ r≤ m`, be a (possibly) partial instantiation of the recursively +uniform parameters of :math:`Γ_P`. We have: + +.. inference:: Ind-Family + + \left\{\begin{array}{l} + \ind{p}{Γ_I}{Γ_C} \in E\\ + (E[] ⊢ q_l : P'_l)_{l=1\ldots r}\\ + (E[] ⊢ P'_l ≤_{βδιζη} \subst{P_l}{p_u}{q_u}_{u=1\ldots l-1})_{l=1\ldots r}\\ + 1 \leq j \leq k + \end{array} + \right. + ----------------------------- + E[] ⊢ I_j~q_1 … q_r :∀ [p_{r+1} :P_{r+1} ;~…;~p_p :P_p], (A_j)_{/s_j} + +provided that the following side conditions hold: + + + :math:`Γ_{P′}` is the context obtained from :math:`Γ_P` by replacing each :math:`P_l` that is + an arity with :math:`P_l'` for :math:`1≤ l ≤ r` (notice that :math:`P_l` arity implies :math:`P_l'` + arity since :math:`E[] ⊢ P_l' ≤_{βδιζη} \subst{P_l}{p_u}{q_u}_{u=1\ldots l-1}`); + + there are sorts :math:`s_i`, for :math:`1 ≤ i ≤ k` such that, for + :math:`Γ_{I'} = [I_1 :∀ Γ_{P'} ,(A_1)_{/s_1} ;~…;~I_k :∀ Γ_{P'} ,(A_k)_{/s_k}]` + we have :math:`(E[Γ_{I′} ;Γ_{P′}] ⊢ C_i : s_{q_i})_{i=1… n}` ; + + the sorts :math:`s_i` are such that all eliminations, to + :math:`\Prop`, :math:`\Set` and :math:`\Type(j)`, are allowed + (see Section :ref:`Destructors`). + + + +Notice that if :math:`I_j~q_1 … q_r` is typable using the rules **Ind-Const** and +**App**, then it is typable using the rule **Ind-Family**. Conversely, the +extended theory is not stronger than the theory without **Ind-Family**. We +get an equiconsistency result by mapping each :math:`\ind{p}{Γ_I}{Γ_C}` +occurring into a given derivation into as many different inductive +types and constructors as the number of different (partial) +replacements of sorts, needed for this derivation, in the parameters +that are arities (this is possible because :math:`\ind{p}{Γ_I}{Γ_C}` well-formed +implies that :math:`\ind{p}{Γ_{I'}}{Γ_{C'}}` is well-formed and has the +same allowed eliminations, where :math:`Γ_{I′}` is defined as above and +:math:`Γ_{C′} = [c_1 :∀ Γ_{P′} ,C_1 ;~…;~c_n :∀ Γ_{P′} ,C_n ]`). That is, the changes in the +types of each partial instance :math:`q_1 … q_r` can be characterized by the +ordered sets of arity sorts among the types of parameters, and to each +signature is associated a new inductive definition with fresh names. +Conversion is preserved as any (partial) instance :math:`I_j~q_1 … q_r` or +:math:`C_i~q_1 … q_r` is mapped to the names chosen in the specific instance of +:math:`\ind{p}{Γ_I}{Γ_C}`. + +In practice, the rule **Ind-Family** is used by |Coq| only when all the +inductive types of the inductive definition are declared with an arity +whose sort is in the Type hierarchy. Then, the polymorphism is over +the parameters whose type is an arity of sort in the Type hierarchy. +The sorts :math:`s_j` are chosen canonically so that each :math:`s_j` is minimal with +respect to the hierarchy :math:`\Prop ⊂ \Set_p ⊂ \Type` where :math:`\Set_p` is predicative +:math:`\Set`. More precisely, an empty or small singleton inductive definition +(i.e. an inductive definition of which all inductive types are +singleton – see Section :ref:`Destructors`) is set in :math:`\Prop`, a small non-singleton +inductive type is set in :math:`\Set` (even in case :math:`\Set` is impredicative – see +Section The-Calculus-of-Inductive-Construction-with-impredicative-Set_), +and otherwise in the Type hierarchy. + +Note that the side-condition about allowed elimination sorts in the +rule **Ind-Family** is just to avoid to recompute the allowed elimination +sorts at each instance of a pattern matching (see Section :ref:`Destructors`). As +an example, let us consider the following definition: + +.. example:: + + .. coqtop:: in + + Inductive option (A:Type) : Type := + | None : option A + | Some : A -> option A. + +As the definition is set in the Type hierarchy, it is used +polymorphically over its parameters whose types are arities of a sort +in the Type hierarchy. Here, the parameter :math:`A` has this property, hence, +if :g:`option` is applied to a type in :math:`\Set`, the result is in :math:`\Set`. Note that +if :g:`option` is applied to a type in :math:`\Prop`, then, the result is not set in +:math:`\Prop` but in :math:`\Set` still. This is because :g:`option` is not a singleton type +(see Section :ref:`Destructors`) and it would lose the elimination to :math:`\Set` and :math:`\Type` +if set in :math:`\Prop`. + +.. example:: + + .. coqtop:: all + + Check (fun A:Set => option A). + Check (fun A:Prop => option A). + +Here is another example. + +.. example:: + + .. coqtop:: in + + Inductive prod (A B:Type) : Type := pair : A -> B -> prod A B. + +As :g:`prod` is a singleton type, it will be in :math:`\Prop` if applied twice to +propositions, in :math:`\Set` if applied twice to at least one type in :math:`\Set` and +none in :math:`\Type`, and in :math:`\Type` otherwise. In all cases, the three kind of +eliminations schemes are allowed. + +.. example:: + + .. coqtop:: all + + Check (fun A:Set => prod A). + Check (fun A:Prop => prod A A). + Check (fun (A:Prop) (B:Set) => prod A B). + Check (fun (A:Type) (B:Prop) => prod A B). + +.. note:: + Template polymorphism used to be called “sort-polymorphism of + inductive types” before universe polymorphism + (see Chapter :ref:`polymorphicuniverses`) was introduced. + + +.. _Destructors: + +Destructors +~~~~~~~~~~~~~~~~~ + +The specification of inductive definitions with arities and +constructors is quite natural. But we still have to say how to use an +object in an inductive type. + +This problem is rather delicate. There are actually several different +ways to do that. Some of them are logically equivalent but not always +equivalent from the computational point of view or from the user point +of view. + +From the computational point of view, we want to be able to define a +function whose domain is an inductively defined type by using a +combination of case analysis over the possible constructors of the +object and recursion. + +Because we need to keep a consistent theory and also we prefer to keep +a strongly normalizing reduction, we cannot accept any sort of +recursion (even terminating). So the basic idea is to restrict +ourselves to primitive recursive functions and functionals. + +For instance, assuming a parameter :math:`A:\Set` exists in the local context, +we want to build a function :math:`\length` of type :math:`\List~A → \nat` which computes +the length of the list, such that :math:`(\length~(\Nil~A)) = \nO` and +:math:`(\length~(\cons~A~a~l)) = (\nS~(\length~l))`. +We want these equalities to be +recognized implicitly and taken into account in the conversion rule. + +From the logical point of view, we have built a type family by giving +a set of constructors. We want to capture the fact that we do not have +any other way to build an object in this type. So when trying to prove +a property about an object :math:`m` in an inductive type it is enough +to enumerate all the cases where :math:`m` starts with a different +constructor. + +In case the inductive definition is effectively a recursive one, we +want to capture the extra property that we have built the smallest +fixed point of this recursive equation. This says that we are only +manipulating finite objects. This analysis provides induction +principles. For instance, in order to prove +:math:`∀ l:\List~A,~(\kw{has}\_\kw{length}~A~l~(\length~l))` it is enough to prove: + + ++ :math:`(\kw{has}\_\kw{length}~A~(\Nil~A)~(\length~(\Nil~A)))` ++ :math:`∀ a:A,~∀ l:\List~A,~(\kw{has}\_\kw{length}~A~l~(\length~l)) →` + :math:`(\kw{has}\_\kw{length}~A~(\cons~A~a~l)~(\length~(\cons~A~a~l)))` + + +which given the conversion equalities satisfied by :math:`\length` is the same +as proving: + + ++ :math:`(\kw{has}\_\kw{length}~A~(\Nil~A)~\nO)` ++ :math:`∀ a:A,~∀ l:\List~A,~(\kw{has}\_\kw{length}~A~l~(\length~l)) →` + :math:`(\kw{has}\_\kw{length}~A~(\cons~A~a~l)~(\nS~(\length~l)))` + + +One conceptually simple way to do that, following the basic scheme +proposed by Martin-Löf in his Intuitionistic Type Theory, is to +introduce for each inductive definition an elimination operator. At +the logical level it is a proof of the usual induction principle and +at the computational level it implements a generic operator for doing +primitive recursion over the structure. + +But this operator is rather tedious to implement and use. We choose in +this version of |Coq| to factorize the operator for primitive recursion +into two more primitive operations as was first suggested by Th. +Coquand in :cite:`Coq92`. One is the definition by pattern matching. The +second one is a definition by guarded fixpoints. + + +.. _match-construction: + +The match ... with ... end construction ++++++++++++++++++++++++++++++++++++++++ + +The basic idea of this operator is that we have an object :math:`m` in an +inductive type :math:`I` and we want to prove a property which possibly +depends on :math:`m`. For this, it is enough to prove the property for +:math:`m = (c_i~u_1 … u_{p_i} )` for each constructor of :math:`I`. +The |Coq| term for this proof +will be written: + +.. math:: + \Match~m~\with~(c_1~x_{11} ... x_{1p_1} ) ⇒ f_1 | … | (c_n~x_{n1} ... x_{np_n} ) ⇒ f_n~\kwend + +In this expression, if :math:`m` eventually happens to evaluate to +:math:`(c_i~u_1 … u_{p_i})` then the expression will behave as specified in its :math:`i`-th branch +and it will reduce to :math:`f_i` where the :math:`x_{i1} …x_{ip_i}` are replaced by the +:math:`u_1 … u_{p_i}` according to the ι-reduction. + +Actually, for type checking a :math:`\Match…\with…\kwend` expression we also need +to know the predicate :math:`P` to be proved by case analysis. In the general +case where :math:`I` is an inductively defined :math:`n`-ary relation, :math:`P` is a predicate +over :math:`n+1` arguments: the :math:`n` first ones correspond to the arguments of :math:`I` +(parameters excluded), and the last one corresponds to object :math:`m`. |Coq| +can sometimes infer this predicate but sometimes not. The concrete +syntax for describing this predicate uses the :math:`\as…\In…\return` +construction. For instance, let us assume that :math:`I` is an unary predicate +with one parameter and one argument. The predicate is made explicit +using the syntax: + +.. math:: + \Match~m~\as~x~\In~I~\_~a~\return~P~\with~ + (c_1~x_{11} ... x_{1p_1} ) ⇒ f_1 | … + | (c_n~x_{n1} ... x_{np_n} ) ⇒ f_n~\kwend + +The :math:`\as` part can be omitted if either the result type does not depend +on :math:`m` (non-dependent elimination) or :math:`m` is a variable (in this case, :math:`m` +can occur in :math:`P` where it is considered a bound variable). The :math:`\In` part +can be omitted if the result type does not depend on the arguments +of :math:`I`. Note that the arguments of :math:`I` corresponding to parameters *must* +be :math:`\_`, because the result type is not generalized to all possible +values of the parameters. The other arguments of :math:`I` (sometimes called +indices in the literature) have to be variables (:math:`a` above) and these +variables can occur in :math:`P`. The expression after :math:`\In` must be seen as an +*inductive type pattern*. Notice that expansion of implicit arguments +and notations apply to this pattern. For the purpose of presenting the +inference rules, we use a more compact notation: + +.. math:: + \case(m,(λ a x . P), λ x_{11} ... x_{1p_1} . f_1~| … |~λ x_{n1} ...x_{np_n} . f_n ) + + +.. _Allowed-elimination-sorts: + +**Allowed elimination sorts.** An important question for building the typing rule for :math:`\Match` is what +can be the type of :math:`λ a x . P` with respect to the type of :math:`m`. If :math:`m:I` +and :math:`I:A` and :math:`λ a x . P : B` then by :math:`[I:A|B]` we mean that one can use +:math:`λ a x . P` with :math:`m` in the above match-construct. + + +.. _cic_notations: + +**Notations.** The :math:`[I:A|B]` is defined as the smallest relation satisfying the +following rules: We write :math:`[I|B]` for :math:`[I:A|B]` where :math:`A` is the type of :math:`I`. + +The case of inductive types in sorts :math:`\Set` or :math:`\Type` is simple. +There is no restriction on the sort of the predicate to be eliminated. + +.. inference:: Prod + + [(I~x):A′|B′] + ----------------------- + [I:∀ x:A,~A′|∀ x:A,~B′] + + +.. inference:: Set & Type + + s_1 ∈ \{\Set,\Type(j)\} + s_2 ∈ \Sort + ---------------- + [I:s_1 |I→ s_2 ] + + +The case of Inductive definitions of sort :math:`\Prop` is a bit more +complicated, because of our interpretation of this sort. The only +harmless allowed eliminations, are the ones when predicate :math:`P` +is also of sort :math:`\Prop` or is of the morally smaller sort +:math:`\SProp`. + +.. inference:: Prop + + s ∈ \{\SProp,\Prop\} + -------------------- + [I:\Prop|I→s] + + +:math:`\Prop` is the type of logical propositions, the proofs of properties :math:`P` in +:math:`\Prop` could not be used for computation and are consequently ignored by +the extraction mechanism. Assume :math:`A` and :math:`B` are two propositions, and the +logical disjunction :math:`A ∨ B` is defined inductively by: + +.. example:: + + .. coqtop:: in + + Inductive or (A B:Prop) : Prop := + or_introl : A -> or A B | or_intror : B -> or A B. + + +The following definition which computes a boolean value by case over +the proof of :g:`or A B` is not accepted: + +.. example:: + + .. coqtop:: all + + Fail Definition choice (A B: Prop) (x:or A B) := + match x with or_introl _ _ a => true | or_intror _ _ b => false end. + +From the computational point of view, the structure of the proof of +:g:`(or A B)` in this term is needed for computing the boolean value. + +In general, if :math:`I` has type :math:`\Prop` then :math:`P` cannot have type :math:`I→\Set`, because +it will mean to build an informative proof of type :math:`(P~m)` doing a case +analysis over a non-computational object that will disappear in the +extracted program. But the other way is safe with respect to our +interpretation we can have :math:`I` a computational object and :math:`P` a +non-computational one, it just corresponds to proving a logical property +of a computational object. + +In the same spirit, elimination on :math:`P` of type :math:`I→\Type` cannot be allowed +because it trivially implies the elimination on :math:`P` of type :math:`I→ \Set` by +cumulativity. It also implies that there are two proofs of the same +property which are provably different, contradicting the +proof-irrelevance property which is sometimes a useful axiom: + +.. example:: + + .. coqtop:: all + + Axiom proof_irrelevance : forall (P : Prop) (x y : P), x=y. + +The elimination of an inductive type of sort :math:`\Prop` on a predicate +:math:`P` of type :math:`I→ \Type` leads to a paradox when applied to impredicative +inductive definition like the second-order existential quantifier +:g:`exProp` defined above, because it gives access to the two projections on +this type. + + +.. _Empty-and-singleton-elimination: + +**Empty and singleton elimination.** There are special inductive definitions in +:math:`\Prop` for which more eliminations are allowed. + +.. inference:: Prop-extended + + I~\kw{is an empty or singleton definition} + s ∈ \Sort + ------------------------------------- + [I:\Prop|I→ s] + +A *singleton definition* has only one constructor and all the +arguments of this constructor have type :math:`\Prop`. In that case, there is a +canonical way to interpret the informative extraction on an object in +that type, such that the elimination on any sort :math:`s` is legal. Typical +examples are the conjunction of non-informative propositions and the +equality. If there is a hypothesis :math:`h:a=b` in the local context, it can +be used for rewriting not only in logical propositions but also in any +type. + +.. example:: + + .. coqtop:: all + + Print eq_rec. + Require Extraction. + Extraction eq_rec. + +An empty definition has no constructors, in that case also, +elimination on any sort is allowed. + +.. _Eliminaton-for-SProp: + +Inductive types in :math:`\SProp` must have no constructors (i.e. be +empty) to be eliminated to produce relevant values. + +Note that thanks to proof irrelevance elimination functions can be +produced for other types, for instance the elimination for a unit type +is the identity. + +.. _Type-of-branches: + +**Type of branches.** +Let :math:`c` be a term of type :math:`C`, we assume :math:`C` is a type of constructor for an +inductive type :math:`I`. Let :math:`P` be a term that represents the property to be +proved. We assume :math:`r` is the number of parameters and :math:`s` is the number of +arguments. + +We define a new type :math:`\{c:C\}^P` which represents the type of the branch +corresponding to the :math:`c:C` constructor. + +.. math:: + \begin{array}{ll} + \{c:(I~q_1\ldots q_r\ t_1 \ldots t_s)\}^P &\equiv (P~t_1\ldots ~t_s~c) \\ + \{c:∀ x:T,~C\}^P &\equiv ∀ x:T,~\{(c~x):C\}^P + \end{array} + +We write :math:`\{c\}^P` for :math:`\{c:C\}^P` with :math:`C` the type of :math:`c`. + + +.. example:: + + The following term in concrete syntax:: + + match t as l return P' with + | nil _ => t1 + | cons _ hd tl => t2 + end + + + can be represented in abstract syntax as + + .. math:: + \case(t,P,f_1 | f_2 ) + + where + + .. math:: + :nowrap: + + \begin{eqnarray*} + P & = & λ l.~P^\prime\\ + f_1 & = & t_1\\ + f_2 & = & λ (hd:\nat).~λ (tl:\List~\nat).~t_2 + \end{eqnarray*} + + According to the definition: + + .. math:: + \{(\Nil~\nat)\}^P ≡ \{(\Nil~\nat) : (\List~\nat)\}^P ≡ (P~(\Nil~\nat)) + + .. math:: + + \begin{array}{rl} + \{(\cons~\nat)\}^P & ≡\{(\cons~\nat) : (\nat→\List~\nat→\List~\nat)\}^P \\ + & ≡∀ n:\nat,~\{(\cons~\nat~n) : (\List~\nat→\List~\nat)\}^P \\ + & ≡∀ n:\nat,~∀ l:\List~\nat,~\{(\cons~\nat~n~l) : (\List~\nat)\}^P \\ + & ≡∀ n:\nat,~∀ l:\List~\nat,~(P~(\cons~\nat~n~l)). + \end{array} + + Given some :math:`P` then :math:`\{(\Nil~\nat)\}^P` represents the expected type of :math:`f_1`, + and :math:`\{(\cons~\nat)\}^P` represents the expected type of :math:`f_2`. + + +.. _Typing-rule: + +**Typing rule.** +Our very general destructor for inductive definition enjoys the +following typing rule + +.. inference:: match + + \begin{array}{l} + E[Γ] ⊢ c : (I~q_1 … q_r~t_1 … t_s ) \\ + E[Γ] ⊢ P : B \\ + [(I~q_1 … q_r)|B] \\ + (E[Γ] ⊢ f_i : \{(c_{p_i}~q_1 … q_r)\}^P)_{i=1… l} + \end{array} + ------------------------------------------------ + E[Γ] ⊢ \case(c,P,f_1 |… |f_l ) : (P~t_1 … t_s~c) + +provided :math:`I` is an inductive type in a +definition :math:`\ind{r}{Γ_I}{Γ_C}` with :math:`Γ_C = [c_1 :C_1 ;~…;~c_n :C_n ]` and +:math:`c_{p_1} … c_{p_l}` are the only constructors of :math:`I`. + + + +.. example:: + + Below is a typing rule for the term shown in the previous example: + + .. inference:: list example + + \begin{array}{l} + E[Γ] ⊢ t : (\List ~\nat) \\ + E[Γ] ⊢ P : B \\ + [(\List ~\nat)|B] \\ + E[Γ] ⊢ f_1 : \{(\Nil ~\nat)\}^P \\ + E[Γ] ⊢ f_2 : \{(\cons ~\nat)\}^P + \end{array} + ------------------------------------------------ + E[Γ] ⊢ \case(t,P,f_1 |f_2 ) : (P~t) + + +.. _Definition-of-ι-reduction: + +**Definition of ι-reduction.** +We still have to define the ι-reduction in the general case. + +An ι-redex is a term of the following form: + +.. math:: + \case((c_{p_i}~q_1 … q_r~a_1 … a_m ),P,f_1 |… |f_l ) + +with :math:`c_{p_i}` the :math:`i`-th constructor of the inductive type :math:`I` with :math:`r` +parameters. + +The ι-contraction of this term is :math:`(f_i~a_1 … a_m )` leading to the +general reduction rule: + +.. math:: + \case((c_{p_i}~q_1 … q_r~a_1 … a_m ),P,f_1 |… |f_l ) \triangleright_ι (f_i~a_1 … a_m ) + + +.. _Fixpoint-definitions: + +Fixpoint definitions +~~~~~~~~~~~~~~~~~~~~ + +The second operator for elimination is fixpoint definition. This +fixpoint may involve several mutually recursive definitions. The basic +concrete syntax for a recursive set of mutually recursive declarations +is (with :math:`Γ_i` contexts): + +.. math:: + \fix~f_1 (Γ_1 ) :A_1 :=t_1~\with … \with~f_n (Γ_n ) :A_n :=t_n + + +The terms are obtained by projections from this set of declarations +and are written + +.. math:: + \fix~f_1 (Γ_1 ) :A_1 :=t_1~\with … \with~f_n (Γ_n ) :A_n :=t_n~\for~f_i + +In the inference rules, we represent such a term by + +.. math:: + \Fix~f_i\{f_1 :A_1':=t_1' … f_n :A_n':=t_n'\} + +with :math:`t_i'` (resp. :math:`A_i'`) representing the term :math:`t_i` abstracted (resp. +generalized) with respect to the bindings in the context :math:`Γ_i`, namely +:math:`t_i'=λ Γ_i . t_i` and :math:`A_i'=∀ Γ_i , A_i`. + + +Typing rule ++++++++++++ + +The typing rule is the expected one for a fixpoint. + +.. inference:: Fix + + (E[Γ] ⊢ A_i : s_i )_{i=1… n} + (E[Γ;~f_1 :A_1 ;~…;~f_n :A_n ] ⊢ t_i : A_i )_{i=1… n} + ------------------------------------------------------- + E[Γ] ⊢ \Fix~f_i\{f_1 :A_1 :=t_1 … f_n :A_n :=t_n \} : A_i + + +Any fixpoint definition cannot be accepted because non-normalizing +terms allow proofs of absurdity. The basic scheme of recursion that +should be allowed is the one needed for defining primitive recursive +functionals. In that case the fixpoint enjoys a special syntactic +restriction, namely one of the arguments belongs to an inductive type, +the function starts with a case analysis and recursive calls are done +on variables coming from patterns and representing subterms. For +instance in the case of natural numbers, a proof of the induction +principle of type + +.. math:: + ∀ P:\nat→\Prop,~(P~\nO)→(∀ n:\nat,~(P~n)→(P~(\nS~n)))→ ∀ n:\nat,~(P~n) + +can be represented by the term: + +.. math:: + \begin{array}{l} + λ P:\nat→\Prop.~λ f:(P~\nO).~λ g:(∀ n:\nat,~(P~n)→(P~(\nS~n))).\\ + \Fix~h\{h:∀ n:\nat,~(P~n):=λ n:\nat.~\case(n,P,f | λp:\nat.~(g~p~(h~p)))\} + \end{array} + +Before accepting a fixpoint definition as being correctly typed, we +check that the definition is “guarded”. A precise analysis of this +notion can be found in :cite:`Gim94`. The first stage is to precise on which +argument the fixpoint will be decreasing. The type of this argument +should be an inductive type. For doing this, the syntax of +fixpoints is extended and becomes + +.. math:: + \Fix~f_i\{f_1/k_1 :A_1:=t_1 … f_n/k_n :A_n:=t_n\} + + +where :math:`k_i` are positive integers. Each :math:`k_i` represents the index of +parameter of :math:`f_i`, on which :math:`f_i` is decreasing. Each :math:`A_i` should be a +type (reducible to a term) starting with at least :math:`k_i` products +:math:`∀ y_1 :B_1 ,~… ∀ y_{k_i} :B_{k_i} ,~A_i'` and :math:`B_{k_i}` an inductive type. + +Now in the definition :math:`t_i`, if :math:`f_j` occurs then it should be applied to +at least :math:`k_j` arguments and the :math:`k_j`-th argument should be +syntactically recognized as structurally smaller than :math:`y_{k_i}`. + +The definition of being structurally smaller is a bit technical. One +needs first to define the notion of *recursive arguments of a +constructor*. For an inductive definition :math:`\ind{r}{Γ_I}{Γ_C}`, if the +type of a constructor :math:`c` has the form +:math:`∀ p_1 :P_1 ,~… ∀ p_r :P_r,~∀ x_1:T_1,~… ∀ x_m :T_m,~(I_j~p_1 … p_r~t_1 … t_s )`, +then the recursive +arguments will correspond to :math:`T_i` in which one of the :math:`I_l` occurs. + +The main rules for being structurally smaller are the following. +Given a variable :math:`y` of an inductively defined type in a declaration +:math:`\ind{r}{Γ_I}{Γ_C}` where :math:`Γ_I` is :math:`[I_1 :A_1 ;~…;~I_k :A_k]`, and :math:`Γ_C` is +:math:`[c_1 :C_1 ;~…;~c_n :C_n ]`, the terms structurally smaller than :math:`y` are: + + ++ :math:`(t~u)` and :math:`λ x:U .~t` when :math:`t` is structurally smaller than :math:`y`. ++ :math:`\case(c,P,f_1 … f_n)` when each :math:`f_i` is structurally smaller than :math:`y`. + If :math:`c` is :math:`y` or is structurally smaller than :math:`y`, its type is an inductive + type :math:`I_p` part of the inductive definition corresponding to :math:`y`. + Each :math:`f_i` corresponds to a type of constructor + :math:`C_q ≡ ∀ p_1 :P_1 ,~…,∀ p_r :P_r ,~∀ y_1 :B_1 ,~… ∀ y_m :B_m ,~(I_p~p_1 … p_r~t_1 … t_s )` + and can consequently be written :math:`λ y_1 :B_1' .~… λ y_m :B_m'.~g_i`. (:math:`B_i'` is + obtained from :math:`B_i` by substituting parameters for variables) the variables + :math:`y_j` occurring in :math:`g_i` corresponding to recursive arguments :math:`B_i` (the + ones in which one of the :math:`I_l` occurs) are structurally smaller than :math:`y`. + + +The following definitions are correct, we enter them using the :cmd:`Fixpoint` +command and show the internal representation. + +.. example:: + + .. coqtop:: all + + Fixpoint plus (n m:nat) {struct n} : nat := + match n with + | O => m + | S p => S (plus p m) + end. + + Print plus. + Fixpoint lgth (A:Set) (l:list A) {struct l} : nat := + match l with + | nil _ => O + | cons _ a l' => S (lgth A l') + end. + Print lgth. + Fixpoint sizet (t:tree) : nat := let (f) := t in S (sizef f) + with sizef (f:forest) : nat := + match f with + | emptyf => O + | consf t f => plus (sizet t) (sizef f) + end. + Print sizet. + +.. _Reduction-rule: + +Reduction rule +++++++++++++++ + +Let :math:`F` be the set of declarations: +:math:`f_1 /k_1 :A_1 :=t_1 …f_n /k_n :A_n:=t_n`. +The reduction for fixpoints is: + +.. math:: + (\Fix~f_i \{F\}~a_1 …a_{k_i}) ~\triangleright_ι~ \subst{t_i}{f_k}{\Fix~f_k \{F\}}_{k=1… n} ~a_1 … a_{k_i} + +when :math:`a_{k_i}` starts with a constructor. This last restriction is needed +in order to keep strong normalization and corresponds to the reduction +for primitive recursive operators. The following reductions are now +possible: + +.. math:: + :nowrap: + + \begin{eqnarray*} + \plus~(\nS~(\nS~\nO))~(\nS~\nO)~& \trii & \nS~(\plus~(\nS~\nO)~(\nS~\nO))\\ + & \trii & \nS~(\nS~(\plus~\nO~(\nS~\nO)))\\ + & \trii & \nS~(\nS~(\nS~\nO))\\ + \end{eqnarray*} + +.. _Mutual-induction: + +**Mutual induction** + +The principles of mutual induction can be automatically generated +using the Scheme command described in Section :ref:`proofschemes-induction-principles`. + + +.. _Admissible-rules-for-global-environments: + +Admissible rules for global environments +-------------------------------------------- + +From the original rules of the type system, one can show the +admissibility of rules which change the local context of definition of +objects in the global environment. We show here the admissible rules +that are used in the discharge mechanism at the end of a section. + + +.. _Abstraction: + +**Abstraction.** +One can modify a global declaration by generalizing it over a +previously assumed constant :math:`c`. For doing that, we need to modify the +reference to the global declaration in the subsequent global +environment and local context by explicitly applying this constant to +the constant :math:`c`. + +Below, if :math:`Γ` is a context of the form :math:`[y_1 :A_1 ;~…;~y_n :A_n]`, we write +:math:`∀x:U,~\subst{Γ}{c}{x}` to mean +:math:`[y_1 :∀ x:U,~\subst{A_1}{c}{x};~…;~y_n :∀ x:U,~\subst{A_n}{c}{x}]` +and :math:`\subst{E}{|Γ|}{|Γ|c}` to mean the parallel substitution +:math:`E\{y_1 /(y_1~c)\}…\{y_n/(y_n~c)\}`. + + +.. _First-abstracting-property: + +**First abstracting property:** + +.. math:: + \frac{\WF{E;~c:U;~E′;~c′:=t:T;~E″}{Γ}} + {\WF{E;~c:U;~E′;~c′:=λ x:U.~\subst{t}{c}{x}:∀x:U,~\subst{T}{c}{x};~\subst{E″}{c′}{(c′~c)}} + {\subst{Γ}{c′}{(c′~c)}}} + + +.. math:: + \frac{\WF{E;~c:U;~E′;~c′:T;~E″}{Γ}} + {\WF{E;~c:U;~E′;~c′:∀ x:U,~\subst{T}{c}{x};~\subst{E″}{c′}{(c′~c)}}{\subst{Γ}{c′}{(c′~c)}}} + +.. math:: + \frac{\WF{E;~c:U;~E′;~\ind{p}{Γ_I}{Γ_C};~E″}{Γ}} + {\WFTWOLINES{E;~c:U;~E′;~\ind{p+1}{∀ x:U,~\subst{Γ_I}{c}{x}}{∀ x:U,~\subst{Γ_C}{c}{x}};~ + \subst{E″}{|Γ_I ;Γ_C |}{|Γ_I ;Γ_C | c}} + {\subst{Γ}{|Γ_I ;Γ_C|}{|Γ_I ;Γ_C | c}}} + +One can similarly modify a global declaration by generalizing it over +a previously defined constant :math:`c`. Below, if :math:`Γ` is a context of the form +:math:`[y_1 :A_1 ;~…;~y_n :A_n]`, we write :math:`\subst{Γ}{c}{u}` to mean +:math:`[y_1 :\subst{A_1} {c}{u};~…;~y_n:\subst{A_n} {c}{u}]`. + + +.. _Second-abstracting-property: + +**Second abstracting property:** + +.. math:: + \frac{\WF{E;~c:=u:U;~E′;~c′:=t:T;~E″}{Γ}} + {\WF{E;~c:=u:U;~E′;~c′:=(\letin{x}{u:U}{\subst{t}{c}{x}}):\subst{T}{c}{u};~E″}{Γ}} + +.. math:: + \frac{\WF{E;~c:=u:U;~E′;~c′:T;~E″}{Γ}} + {\WF{E;~c:=u:U;~E′;~c′:\subst{T}{c}{u};~E″}{Γ}} + +.. math:: + \frac{\WF{E;~c:=u:U;~E′;~\ind{p}{Γ_I}{Γ_C};~E″}{Γ}} + {\WF{E;~c:=u:U;~E′;~\ind{p}{\subst{Γ_I}{c}{u}}{\subst{Γ_C}{c}{u}};~E″}{Γ}} + +.. _Pruning-the-local-context: + +**Pruning the local context.** +If one abstracts or substitutes constants with the above rules then it +may happen that some declared or defined constant does not occur any +more in the subsequent global environment and in the local context. +One can consequently derive the following property. + + +.. _First-pruning-property: + +.. inference:: First pruning property: + + \WF{E;~c:U;~E′}{Γ} + c~\kw{does not occur in}~E′~\kw{and}~Γ + -------------------------------------- + \WF{E;E′}{Γ} + + +.. _Second-pruning-property: + +.. inference:: Second pruning property: + + \WF{E;~c:=u:U;~E′}{Γ} + c~\kw{does not occur in}~E′~\kw{and}~Γ + -------------------------------------- + \WF{E;E′}{Γ} + + +.. _Co-inductive-types: + +Co-inductive types +---------------------- + +The implementation contains also co-inductive definitions, which are +types inhabited by infinite objects. More information on co-inductive +definitions can be found in :cite:`Gimenez95b,Gim98,GimCas05`. + + +.. _The-Calculus-of-Inductive-Construction-with-impredicative-Set: + +The Calculus of Inductive Constructions with impredicative Set +----------------------------------------------------------------- + +|Coq| can be used as a type checker for the Calculus of Inductive +Constructions with an impredicative sort :math:`\Set` by using the compiler +option ``-impredicative-set``. For example, using the ordinary `coqtop` +command, the following is rejected, + +.. example:: + + .. coqtop:: all + + Fail Definition id: Set := forall X:Set,X->X. + +while it will type check, if one uses instead the `coqtop` +``-impredicative-set`` option.. + +The major change in the theory concerns the rule for product formation +in the sort :math:`\Set`, which is extended to a domain in any sort: + +.. inference:: ProdImp + + E[Γ] ⊢ T : s + s ∈ \Sort + E[Γ::(x:T)] ⊢ U : \Set + --------------------- + E[Γ] ⊢ ∀ x:T,~U : \Set + +This extension has consequences on the inductive definitions which are +allowed. In the impredicative system, one can build so-called *large +inductive definitions* like the example of second-order existential +quantifier (:g:`exSet`). + +There should be restrictions on the eliminations which can be +performed on such definitions. The elimination rules in the +impredicative system for sort :math:`\Set` become: + + + +.. inference:: Set1 + + s ∈ \{\Prop, \Set\} + ----------------- + [I:\Set|I→ s] + +.. inference:: Set2 + + I~\kw{is a small inductive definition} + s ∈ \{\Type(i)\} + ---------------- + [I:\Set|I→ s] + + diff --git a/doc/sphinx/language/coq-library.rst b/doc/sphinx/language/coq-library.rst new file mode 100644 index 0000000000..d1b95e6203 --- /dev/null +++ b/doc/sphinx/language/coq-library.rst @@ -0,0 +1,1003 @@ +.. _thecoqlibrary: + +The |Coq| library +================= + +.. index:: + single: Theories + + +The |Coq| library is structured into two parts: + + * **The initial library**: it contains elementary logical notions and + data-types. It constitutes the basic state of the system directly + available when running |Coq|; + + * **The standard library**: general-purpose libraries containing various + developments of |Coq| axiomatizations about sets, lists, sorting, + arithmetic, etc. This library comes with the system and its modules + are directly accessible through the ``Require`` command (see + Section :ref:`compiled-files`); + +In addition, user-provided libraries or developments are provided by +|Coq| users' community. These libraries and developments are available +for download at http://coq.inria.fr (see +Section :ref:`userscontributions`). + +This chapter briefly reviews the |Coq| libraries whose contents can +also be browsed at http://coq.inria.fr/stdlib. + + + + +The basic library +----------------- + +This section lists the basic notions and results which are directly +available in the standard |Coq| system. Most of these constructions +are defined in the ``Prelude`` module in directory ``theories/Init`` +at the |Coq| root directory; this includes the modules +``Notations``, +``Logic``, +``Datatypes``, +``Specif``, +``Peano``, +``Wf`` and +``Tactics``. +Module ``Logic_Type`` also makes it in the initial state. + +.. _init-notations: + +Notations +~~~~~~~~~ + +This module defines the parsing and pretty-printing of many symbols +(infixes, prefixes, etc.). However, it does not assign a meaning to +these notations. The purpose of this is to define and fix once for all +the precedence and associativity of very common notations. The main +notations fixed in the initial state are : + +================ ============ =============== +Notation Precedence Associativity +================ ============ =============== +``_ -> _`` 99 right +``_ <-> _`` 95 no +``_ \/ _`` 85 right +``_ /\ _`` 80 right +``~ _`` 75 right +``_ = _`` 70 no +``_ = _ = _`` 70 no +``_ = _ :> _`` 70 no +``_ <> _`` 70 no +``_ <> _ :> _`` 70 no +``_ < _`` 70 no +``_ > _`` 70 no +``_ <= _`` 70 no +``_ >= _`` 70 no +``_ < _ < _`` 70 no +``_ < _ <= _`` 70 no +``_ <= _ < _`` 70 no +``_ <= _ <= _`` 70 no +``_ + _`` 50 left +``_ || _`` 50 left +``_ - _`` 50 left +``_ * _`` 40 left +``_ _`` 40 left +``_ / _`` 40 left +``- _`` 35 right +``/ _`` 35 right +``_ ^ _`` 30 right +================ ============ =============== + +.. _coq-library-logic: + +Logic +~~~~~ + +The basic library of |Coq| comes with the definitions of standard +(intuitionistic) logical connectives (they are defined as inductive +constructions). They are equipped with an appealing syntax enriching the +subclass :token:`form` of the syntactic class :token:`term`. The syntax of +:token:`form` is shown below: + +.. /!\ Please keep the blanks in the lines below, experimentally they produce + a nice last column. Or even better, find a proper way to do this! + +.. productionlist:: + form : True (True) + : False (False) + : ~ `form` (not) + : `form` /\ `form` (and) + : `form` \/ `form` (or) + : `form` -> `form` (primitive implication) + : `form` <-> `form` (iff) + : forall `ident` : `type`, `form` (primitive for all) + : exists `ident` [: `specif`], `form` (ex) + : exists2 `ident` [: `specif`], `form` & `form` (ex2) + : `term` = `term` (eq) + : `term` = `term` :> `specif` (eq) + +.. note:: + + Implication is not defined but primitive (it is a non-dependent + product of a proposition over another proposition). There is also a + primitive universal quantification (it is a dependent product over a + proposition). The primitive universal quantification allows both + first-order and higher-order quantification. + +Propositional Connectives ++++++++++++++++++++++++++ + +.. index:: + single: Connectives + single: True (term) + single: I (term) + single: False (term) + single: not (term) + single: and (term) + single: conj (term) + single: proj1 (term) + single: proj2 (term) + single: or (term) + single: or_introl (term) + single: or_intror (term) + single: iff (term) + single: IF_then_else (term) + +First, we find propositional calculus connectives: + +.. coqdoc:: + + Inductive True : Prop := I. + Inductive False : Prop := . + Definition not (A: Prop) := A -> False. + Inductive and (A B:Prop) : Prop := conj (_:A) (_:B). + Section Projections. + Variables A B : Prop. + Theorem proj1 : A /\ B -> A. + Theorem proj2 : A /\ B -> B. + End Projections. + Inductive or (A B:Prop) : Prop := + | or_introl (_:A) + | or_intror (_:B). + Definition iff (P Q:Prop) := (P -> Q) /\ (Q -> P). + Definition IF_then_else (P Q R:Prop) := P /\ Q \/ ~ P /\ R. + +Quantifiers ++++++++++++ + +.. index:: + single: Quantifiers + single: all (term) + single: ex (term) + single: exists (term) + single: ex_intro (term) + single: ex2 (term) + single: exists2 (term) + single: ex_intro2 (term) + +Then we find first-order quantifiers: + +.. coqtop:: in + + Definition all (A:Set) (P:A -> Prop) := forall x:A, P x. + Inductive ex (A: Set) (P:A -> Prop) : Prop := + ex_intro (x:A) (_:P x). + Inductive ex2 (A:Set) (P Q:A -> Prop) : Prop := + ex_intro2 (x:A) (_:P x) (_:Q x). + +The following abbreviations are allowed: + +====================== ======================================= +``exists x:A, P`` ``ex A (fun x:A => P)`` +``exists x, P`` ``ex _ (fun x => P)`` +``exists2 x:A, P & Q`` ``ex2 A (fun x:A => P) (fun x:A => Q)`` +``exists2 x, P & Q`` ``ex2 _ (fun x => P) (fun x => Q)`` +====================== ======================================= + +The type annotation ``:A`` can be omitted when ``A`` can be +synthesized by the system. + +.. _coq-equality: + +Equality +++++++++ + +.. index:: + single: Equality + single: eq (term) + single: eq_refl (term) + +Then, we find equality, defined as an inductive relation. That is, +given a type ``A`` and an ``x`` of type ``A``, the +predicate :g:`(eq A x)` is the smallest one which contains ``x``. +This definition, due to Christine Paulin-Mohring, is equivalent to +define ``eq`` as the smallest reflexive relation, and it is also +equivalent to Leibniz' equality. + +.. coqtop:: in + + Inductive eq (A:Type) (x:A) : A -> Prop := + eq_refl : eq A x x. + +Lemmas +++++++ + +Finally, a few easy lemmas are provided. + +.. index:: + single: absurd (term) + single: eq_sym (term) + single: eq_trans (term) + single: f_equal (term) + single: sym_not_eq (term) + single: eq_ind_r (term) + single: eq_rec_r (term) + single: eq_rect (term) + single: eq_rect_r (term) + +.. coqdoc:: + + Theorem absurd : forall A C:Prop, A -> ~ A -> C. + Section equality. + Variables A B : Type. + Variable f : A -> B. + Variables x y z : A. + Theorem eq_sym : x = y -> y = x. + Theorem eq_trans : x = y -> y = z -> x = z. + Theorem f_equal : x = y -> f x = f y. + Theorem not_eq_sym : x <> y -> y <> x. + End equality. + Definition eq_ind_r : + forall (A:Type) (x:A) (P:A->Prop), P x -> forall y:A, y = x -> P y. + Definition eq_rec_r : + forall (A:Type) (x:A) (P:A->Set), P x -> forall y:A, y = x -> P y. + Definition eq_rect_r : + forall (A:Type) (x:A) (P:A->Type), P x -> forall y:A, y = x -> P y. + Hint Immediate eq_sym not_eq_sym : core. + +.. index:: + single: f_equal2 ... f_equal5 (term) + +The theorem ``f_equal`` is extended to functions with two to five +arguments. The theorem are names ``f_equal2``, ``f_equal3``, +``f_equal4`` and ``f_equal5``. +For instance ``f_equal3`` is defined the following way. + +.. coqtop:: in abort + + Theorem f_equal3 : + forall (A1 A2 A3 B:Type) (f:A1 -> A2 -> A3 -> B) + (x1 y1:A1) (x2 y2:A2) (x3 y3:A3), + x1 = y1 -> x2 = y2 -> x3 = y3 -> f x1 x2 x3 = f y1 y2 y3. + +.. _datatypes: + +Datatypes +~~~~~~~~~ + +.. index:: + single: Datatypes + +In the basic library, we find in ``Datatypes.v`` the definition +of the basic data-types of programming, +defined as inductive constructions over the sort ``Set``. Some of +them come with a special syntax shown below (this syntax table is common with +the next section :ref:`specification`): + +.. productionlist:: + specif : `specif` * `specif` (prod) + : `specif` + `specif` (sum) + : `specif` + { `specif` } (sumor) + : { `specif` } + { `specif` } (sumbool) + : { `ident` : `specif` | `form` } (sig) + : { `ident` : `specif` | `form` & `form` } (sig2) + : { `ident` : `specif` & `specif` } (sigT) + : { `ident` : `specif` & `specif` & `specif` } (sigT2) + term : (`term`, `term`) (pair) + + +Programming ++++++++++++ + +.. index:: + single: Programming + single: unit (term) + single: tt (term) + single: bool (term) + single: true (term) + single: false (term) + single: nat (term) + single: O (term) + single: S (term) + single: option (term) + single: Some (term) + single: None (term) + single: identity (term) + single: refl_identity (term) + +.. coqtop:: in + + Inductive unit : Set := tt. + Inductive bool : Set := true | false. + Inductive nat : Set := O | S (n:nat). + Inductive option (A:Set) : Set := Some (_:A) | None. + Inductive identity (A:Type) (a:A) : A -> Type := + refl_identity : identity A a a. + +Note that zero is the letter ``O``, and *not* the numeral ``0``. + +The predicate ``identity`` is logically +equivalent to equality but it lives in sort ``Type``. +It is mainly maintained for compatibility. + +We then define the disjoint sum of ``A+B`` of two sets ``A`` and +``B``, and their product ``A*B``. + +.. index:: + single: sum (term) + single: A+B (term) + single: + (term) + single: inl (term) + single: inr (term) + single: prod (term) + single: A*B (term) + single: * (term) + single: pair (term) + single: fst (term) + single: snd (term) + +.. coqtop:: in + + Inductive sum (A B:Set) : Set := inl (_:A) | inr (_:B). + Inductive prod (A B:Set) : Set := pair (_:A) (_:B). + Section projections. + Variables A B : Set. + Definition fst (H: prod A B) := match H with + | pair _ _ x y => x + end. + Definition snd (H: prod A B) := match H with + | pair _ _ x y => y + end. + End projections. + +Some operations on ``bool`` are also provided: ``andb`` (with +infix notation ``&&``), ``orb`` (with +infix notation ``||``), ``xorb``, ``implb`` and ``negb``. + +.. _specification: + +Specification +~~~~~~~~~~~~~ + +The following notions defined in module ``Specif.v`` allow to build new data-types and specifications. +They are available with the syntax shown in the previous section :ref:`datatypes`. + +For instance, given :g:`A:Type` and :g:`P:A->Prop`, the construct +:g:`{x:A | P x}` (in abstract syntax :g:`(sig A P)`) is a +``Type``. We may build elements of this set as :g:`(exist x p)` +whenever we have a witness :g:`x:A` with its justification +:g:`p:P x`. + +From such a :g:`(exist x p)` we may in turn extract its witness +:g:`x:A` (using an elimination construct such as ``match``) but +*not* its justification, which stays hidden, like in an abstract +data-type. In technical terms, one says that ``sig`` is a *weak +(dependent) sum*. A variant ``sig2`` with two predicates is also +provided. + +.. index:: + single: {x:A | P x} (term) + single: sig (term) + single: exist (term) + single: sig2 (term) + single: exist2 (term) + +.. coqtop:: in + + Inductive sig (A:Set) (P:A -> Prop) : Set := exist (x:A) (_:P x). + Inductive sig2 (A:Set) (P Q:A -> Prop) : Set := + exist2 (x:A) (_:P x) (_:Q x). + +A *strong (dependent) sum* :g:`{x:A & P x}` may be also defined, +when the predicate ``P`` is now defined as a +constructor of types in ``Type``. + +.. index:: + single: {x:A & P x} (term) + single: sigT (term) + single: existT (term) + single: sigT2 (term) + single: existT2 (term) + single: projT1 (term) + single: projT2 (term) + +.. coqtop:: in + + Inductive sigT (A:Type) (P:A -> Type) : Type := existT (x:A) (_:P x). + Section Projections2. + Variable A : Type. + Variable P : A -> Type. + Definition projT1 (H:sigT A P) := let (x, h) := H in x. + Definition projT2 (H:sigT A P) := + match H return P (projT1 H) with + existT _ _ x h => h + end. + End Projections2. + Inductive sigT2 (A: Type) (P Q:A -> Type) : Type := + existT2 (x:A) (_:P x) (_:Q x). + +A related non-dependent construct is the constructive sum +:g:`{A}+{B}` of two propositions ``A`` and ``B``. + +.. index:: + single: sumbool (term) + single: left (term) + single: right (term) + single: {A}+{B} (term) + +.. coqtop:: in + + Inductive sumbool (A B:Prop) : Set := left (_:A) | right (_:B). + +This ``sumbool`` construct may be used as a kind of indexed boolean +data-type. An intermediate between ``sumbool`` and ``sum`` is +the mixed ``sumor`` which combines :g:`A:Set` and :g:`B:Prop` +in the construction :g:`A+{B}` in ``Set``. + +.. index:: + single: sumor (term) + single: inleft (term) + single: inright (term) + single: A+{B} (term) + +.. coqtop:: in + + Inductive sumor (A:Set) (B:Prop) : Set := + | inleft (_:A) + | inright (_:B). + +We may define variants of the axiom of choice, like in Martin-Löf's +Intuitionistic Type Theory. + +.. index:: + single: Choice (term) + single: Choice2 (term) + single: bool_choice (term) + +.. coqdoc:: + + Lemma Choice : + forall (S S':Set) (R:S -> S' -> Prop), + (forall x:S, {y : S' | R x y}) -> + {f : S -> S' | forall z:S, R z (f z)}. + Lemma Choice2 : + forall (S S':Set) (R:S -> S' -> Set), + (forall x:S, {y : S' & R x y}) -> + {f : S -> S' & forall z:S, R z (f z)}. + Lemma bool_choice : + forall (S:Set) (R1 R2:S -> Prop), + (forall x:S, {R1 x} + {R2 x}) -> + {f : S -> bool | + forall x:S, f x = true /\ R1 x \/ f x = false /\ R2 x}. + +The next construct builds a sum between a data-type :g:`A:Type` and +an exceptional value encoding errors: + +.. index:: + single: Exc (term) + single: value (term) + single: error (term) + +.. coqtop:: in + + Definition Exc := option. + Definition value := Some. + Definition error := None. + +This module ends with theorems, relating the sorts ``Set`` or +``Type`` and ``Prop`` in a way which is consistent with the +realizability interpretation. + +.. index:: + single: False_rect (term) + single: False_rec (term) + single: eq_rect (term) + single: absurd_set (term) + single: and_rect (term) + +.. coqdoc:: + + Definition except := False_rec. + Theorem absurd_set : forall (A:Prop) (C:Set), A -> ~ A -> C. + Theorem and_rect2 : + forall (A B:Prop) (P:Type), (A -> B -> P) -> A /\ B -> P. + + +Basic Arithmetics +~~~~~~~~~~~~~~~~~ + +The basic library includes a few elementary properties of natural +numbers, together with the definitions of predecessor, addition and +multiplication, in module ``Peano.v``. It also +provides a scope ``nat_scope`` gathering standard notations for +common operations (``+``, ``*``) and a decimal notation for +numbers, allowing for instance to write ``3`` for :g:`S (S (S O)))`. This also works on +the left hand side of a ``match`` expression (see for example +section :tacn:`refine`). This scope is opened by default. + +.. example:: + + The following example is not part of the standard library, but it + shows the usage of the notations: + + .. coqtop:: in reset + + Fixpoint even (n:nat) : bool := + match n with + | 0 => true + | 1 => false + | S (S n) => even n + end. + +.. index:: + single: eq_S (term) + single: pred (term) + single: pred_Sn (term) + single: eq_add_S (term) + single: not_eq_S (term) + single: IsSucc (term) + single: O_S (term) + single: n_Sn (term) + single: plus (term) + single: plus_n_O (term) + single: plus_n_Sm (term) + single: mult (term) + single: mult_n_O (term) + single: mult_n_Sm (term) + +Now comes the content of module ``Peano``: + +.. coqdoc:: + + Theorem eq_S : forall x y:nat, x = y -> S x = S y. + Definition pred (n:nat) : nat := + match n with + | 0 => 0 + | S u => u + end. + Theorem pred_Sn : forall m:nat, m = pred (S m). + Theorem eq_add_S : forall n m:nat, S n = S m -> n = m. + Hint Immediate eq_add_S : core. + Theorem not_eq_S : forall n m:nat, n <> m -> S n <> S m. + Definition IsSucc (n:nat) : Prop := + match n with + | 0 => False + | S p => True + end. + Theorem O_S : forall n:nat, 0 <> S n. + Theorem n_Sn : forall n:nat, n <> S n. + Fixpoint plus (n m:nat) {struct n} : nat := + match n with + | 0 => m + | S p => S (p + m) + end + where "n + m" := (plus n m) : nat_scope. + Lemma plus_n_O : forall n:nat, n = n + 0. + Lemma plus_n_Sm : forall n m:nat, S (n + m) = n + S m. + Fixpoint mult (n m:nat) {struct n} : nat := + match n with + | 0 => 0 + | S p => m + p * m + end + where "n * m" := (mult n m) : nat_scope. + Lemma mult_n_O : forall n:nat, 0 = n * 0. + Lemma mult_n_Sm : forall n m:nat, n * m + n = n * (S m). + + +Finally, it gives the definition of the usual orderings ``le``, +``lt``, ``ge`` and ``gt``. + +.. index:: + single: le (term) + single: le_n (term) + single: le_S (term) + single: lt (term) + single: ge (term) + single: gt (term) + +.. This emits a notation already used warning but it won't be shown to + the user. + +.. coqtop:: in warn + + Inductive le (n:nat) : nat -> Prop := + | le_n : le n n + | le_S : forall m:nat, n <= m -> n <= (S m) + where "n <= m" := (le n m) : nat_scope. + Definition lt (n m:nat) := S n <= m. + Definition ge (n m:nat) := m <= n. + Definition gt (n m:nat) := m < n. + +Properties of these relations are not initially known, but may be +required by the user from modules ``Le`` and ``Lt``. Finally, +``Peano`` gives some lemmas allowing pattern matching, and a double +induction principle. + +.. index:: + single: nat_case (term) + single: nat_double_ind (term) + +.. coqdoc:: + + Theorem nat_case : + forall (n:nat) (P:nat -> Prop), + P 0 -> (forall m:nat, P (S m)) -> P n. + Theorem nat_double_ind : + forall R:nat -> nat -> Prop, + (forall n:nat, R 0 n) -> + (forall n:nat, R (S n) 0) -> + (forall n m:nat, R n m -> R (S n) (S m)) -> forall n m:nat, R n m. + + +Well-founded recursion +~~~~~~~~~~~~~~~~~~~~~~ + +The basic library contains the basics of well-founded recursion and +well-founded induction, in module ``Wf.v``. + +.. index:: + single: Well foundedness + single: Recursion + single: Well founded induction + single: Acc (term) + single: Acc_inv (term) + single: Acc_rect (term) + single: well_founded (term) + +.. coqdoc:: + + Section Well_founded. + Variable A : Type. + Variable R : A -> A -> Prop. + Inductive Acc (x:A) : Prop := + Acc_intro : (forall y:A, R y x -> Acc y) -> Acc x. + Lemma Acc_inv x : Acc x -> forall y:A, R y x -> Acc y. + Definition well_founded := forall a:A, Acc a. + Hypothesis Rwf : well_founded. + Theorem well_founded_induction : + forall P:A -> Set, + (forall x:A, (forall y:A, R y x -> P y) -> P x) -> forall a:A, P a. + Theorem well_founded_ind : + forall P:A -> Prop, + (forall x:A, (forall y:A, R y x -> P y) -> P x) -> forall a:A, P a. + +The automatically generated scheme ``Acc_rect`` +can be used to define functions by fixpoints using +well-founded relations to justify termination. Assuming +extensionality of the functional used for the recursive call, the +fixpoint equation can be proved. + +.. index:: + single: Fix_F (term) + single: fix_eq (term) + single: Fix_F_inv (term) + single: Fix_F_eq (term) + +.. coqdoc:: + + Section FixPoint. + Variable P : A -> Type. + Variable F : forall x:A, (forall y:A, R y x -> P y) -> P x. + Fixpoint Fix_F (x:A) (r:Acc x) {struct r} : P x := + F x (fun (y:A) (p:R y x) => Fix_F y (Acc_inv x r y p)). + Definition Fix (x:A) := Fix_F x (Rwf x). + Hypothesis F_ext : + forall (x:A) (f g:forall y:A, R y x -> P y), + (forall (y:A) (p:R y x), f y p = g y p) -> F x f = F x g. + Lemma Fix_F_eq : + forall (x:A) (r:Acc x), + F x (fun (y:A) (p:R y x) => Fix_F y (Acc_inv x r y p)) = Fix_F x r. + Lemma Fix_F_inv : forall (x:A) (r s:Acc x), Fix_F x r = Fix_F x s. + Lemma fix_eq : forall x:A, Fix x = F x (fun (y:A) (p:R y x) => Fix y). + End FixPoint. + End Well_founded. + +Accessing the Type level +~~~~~~~~~~~~~~~~~~~~~~~~ + +The standard library includes ``Type`` level definitions of counterparts of some +logic concepts and basic lemmas about them. + +The module ``Datatypes`` defines ``identity``, which is the ``Type`` level counterpart +of equality: + +.. index:: + single: identity (term) + +.. coqtop:: in + + Inductive identity (A:Type) (a:A) : A -> Type := + identity_refl : identity A a a. + +Some properties of ``identity`` are proved in the module ``Logic_Type``, which also +provides the definition of ``Type`` level negation: + +.. index:: + single: notT (term) + +.. coqtop:: in + + Definition notT (A:Type) := A -> False. + +Tactics +~~~~~~~ + +A few tactics defined at the user level are provided in the initial +state, in module ``Tactics.v``. They are listed at +http://coq.inria.fr/stdlib, in paragraph ``Init``, link ``Tactics``. + + +The standard library +-------------------- + +Survey +~~~~~~ + +The rest of the standard library is structured into the following +subdirectories: + + * **Logic** : Classical logic and dependent equality + * **Arith** : Basic Peano arithmetic + * **PArith** : Basic positive integer arithmetic + * **NArith** : Basic binary natural number arithmetic + * **ZArith** : Basic relative integer arithmetic + * **Numbers** : Various approaches to natural, integer and cyclic numbers (currently axiomatically and on top of 2^31 binary words) + * **Bool** : Booleans (basic functions and results) + * **Lists** : Monomorphic and polymorphic lists (basic functions and results), Streams (infinite sequences defined with co-inductive types) + * **Sets** : Sets (classical, constructive, finite, infinite, power set, etc.) + * **FSets** : Specification and implementations of finite sets and finite maps (by lists and by AVL trees) + * **Reals** : Axiomatization of real numbers (classical, basic functions, integer part, fractional part, limit, derivative, Cauchy series, power series and results,...) + * **Relations** : Relations (definitions and basic results) + * **Sorting** : Sorted list (basic definitions and heapsort correctness) + * **Strings** : 8-bits characters and strings + * **Wellfounded** : Well-founded relations (basic results) + + +These directories belong to the initial load path of the system, and +the modules they provide are compiled at installation time. So they +are directly accessible with the command ``Require`` (see +Section :ref:`compiled-files`). + +The different modules of the |Coq| standard library are documented +online at http://coq.inria.fr/stdlib. + +Peano’s arithmetic (nat) +~~~~~~~~~~~~~~~~~~~~~~~~ + +.. index:: + single: Peano's arithmetic + single: nat_scope + +While in the initial state, many operations and predicates of Peano's +arithmetic are defined, further operations and results belong to other +modules. For instance, the decidability of the basic predicates are +defined here. This is provided by requiring the module ``Arith``. + +The following table describes the notations available in scope +``nat_scope`` : + +=============== =================== +Notation Interpretation +=============== =================== +``_ < _`` ``lt`` +``_ <= _`` ``le`` +``_ > _`` ``gt`` +``_ >= _`` ``ge`` +``x < y < z`` ``x < y /\ y < z`` +``x < y <= z`` ``x < y /\ y <= z`` +``x <= y < z`` ``x <= y /\ y < z`` +``x <= y <= z`` ``x <= y /\ y <= z`` +``_ + _`` ``plus`` +``_ - _`` ``minus`` +``_ * _`` ``mult`` +=============== =================== + + +Notations for integer arithmetics +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. index:: + single: Arithmetical notations + single: + (term) + single: * (term) + single: - (term) + singel: / (term) + single: <= (term) + single: >= (term) + single: < (term) + single: > (term) + single: ?= (term) + single: mod (term) + + +The following table describes the syntax of expressions +for integer arithmetics. It is provided by requiring and opening the module ``ZArith`` and opening scope ``Z_scope``. +It specifies how notations are interpreted and, when not +already reserved, the precedence and associativity. + +=============== ==================== ========== ============= +Notation Interpretation Precedence Associativity +=============== ==================== ========== ============= +``_ < _`` ``Z.lt`` +``_ <= _`` ``Z.le`` +``_ > _`` ``Z.gt`` +``_ >= _`` ``Z.ge`` +``x < y < z`` ``x < y /\ y < z`` +``x < y <= z`` ``x < y /\ y <= z`` +``x <= y < z`` ``x <= y /\ y < z`` +``x <= y <= z`` ``x <= y /\ y <= z`` +``_ ?= _`` ``Z.compare`` 70 no +``_ + _`` ``Z.add`` +``_ - _`` ``Z.sub`` +``_ * _`` ``Z.mul`` +``_ / _`` ``Z.div`` +``_ mod _`` ``Z.modulo`` 40 no +``- _`` ``Z.opp`` +``_ ^ _`` ``Z.pow`` +=============== ==================== ========== ============= + + +.. example:: + + .. coqtop:: all reset + + Require Import ZArith. + Check (2 + 3)%Z. + Open Scope Z_scope. + Check 2 + 3. + + +Real numbers library +~~~~~~~~~~~~~~~~~~~~ + +Notations for real numbers +++++++++++++++++++++++++++ + +This is provided by requiring and opening the module ``Reals`` and +opening scope ``R_scope``. This set of notations is very similar to +the notation for integer arithmetics. The inverse function was added. + +=============== =================== +Notation Interpretation +=============== =================== +``_ < _`` ``Rlt`` +``_ <= _`` ``Rle`` +``_ > _`` ``Rgt`` +``_ >= _`` ``Rge`` +``x < y < z`` ``x < y /\ y < z`` +``x < y <= z`` ``x < y /\ y <= z`` +``x <= y < z`` ``x <= y /\ y < z`` +``x <= y <= z`` ``x <= y /\ y <= z`` +``_ + _`` ``Rplus`` +``_ - _`` ``Rminus`` +``_ * _`` ``Rmult`` +``_ / _`` ``Rdiv`` +``- _`` ``Ropp`` +``/ _`` ``Rinv`` +``_ ^ _`` ``pow`` +=============== =================== + +.. example:: + + .. coqtop:: all reset + + Require Import Reals. + Check (2 + 3)%R. + Open Scope R_scope. + Check 2 + 3. + +Some tactics for real numbers ++++++++++++++++++++++++++++++ + +In addition to the powerful ``ring``, ``field`` and ``lra`` +tactics (see Chapter :ref:`tactics`), there are also: + +.. tacn:: discrR + :name: discrR + + Proves that two real integer constants are different. + +.. example:: + + .. coqtop:: all reset + + Require Import DiscrR. + Open Scope R_scope. + Goal 5 <> 0. + discrR. + +.. tacn:: split_Rabs + :name: split_Rabs + + Allows unfolding the ``Rabs`` constant and splits corresponding conjunctions. + +.. example:: + + .. coqtop:: all reset + + Require Import Reals. + Open Scope R_scope. + Goal forall x:R, x <= Rabs x. + intro; split_Rabs. + +.. tacn:: split_Rmult + :name: split_Rmult + + Splits a condition that a product is non null into subgoals + corresponding to the condition on each operand of the product. + +.. example:: + + .. coqtop:: all reset + + Require Import Reals. + Open Scope R_scope. + Goal forall x y z:R, x * y * z <> 0. + intros; split_Rmult. + +These tactics has been written with the tactic language |Ltac| +described in Chapter :ref:`ltac`. + +List library +~~~~~~~~~~~~ + +.. index:: + single: Notations for lists + single: length (term) + single: head (term) + single: tail (term) + single: app (term) + single: rev (term) + single: nth (term) + single: map (term) + single: flat_map (term) + single: fold_left (term) + single: fold_right (term) + +Some elementary operations on polymorphic lists are defined here. +They can be accessed by requiring module ``List``. + +It defines the following notions: + + * ``length`` + * ``head`` : first element (with default) + * ``tail`` : all but first element + * ``app`` : concatenation + * ``rev`` : reverse + * ``nth`` : accessing n-th element (with default) + * ``map`` : applying a function + * ``flat_map`` : applying a function returning lists + * ``fold_left`` : iterator (from head to tail) + * ``fold_right`` : iterator (from tail to head) + +The following table shows notations available when opening scope ``list_scope``. + +========== ============== ========== ============= +Notation Interpretation Precedence Associativity +========== ============== ========== ============= +``_ ++ _`` ``app`` 60 right +``_ :: _`` ``cons`` 60 right +========== ============== ========== ============= + +.. _userscontributions: + +Users’ contributions +-------------------- + +Numerous users' contributions have been collected and are available at +URL http://coq.inria.fr/opam/www/. On this web page, you have a list +of all contributions with informations (author, institution, quick +description, etc.) and the possibility to download them one by one. +You will also find informations on how to submit a new +contribution. diff --git a/doc/sphinx/language/gallina-extensions.rst b/doc/sphinx/language/gallina-extensions.rst new file mode 100644 index 0000000000..695dea222f --- /dev/null +++ b/doc/sphinx/language/gallina-extensions.rst @@ -0,0 +1,2389 @@ +.. _extensionsofgallina: + +Extensions of |Gallina| +======================= + +|Gallina| is the kernel language of |Coq|. We describe here extensions of +|Gallina|’s syntax. + +.. _record-types: + +Record types +---------------- + +The :cmd:`Record` construction is a macro allowing the definition of +records as is done in many programming languages. Its syntax is +described in the grammar below. In fact, the :cmd:`Record` macro is more general +than the usual record types, since it allows also for “manifest” +expressions. In this sense, the :cmd:`Record` construction allows defining +“signatures”. + +.. _record_grammar: + + .. productionlist:: sentence + record : `record_keyword` `record_body` with … with `record_body` + record_keyword : Record | Inductive | CoInductive + record_body : `ident` [ `binders` ] [: `sort` ] := [ `ident` ] { [ `field` ; … ; `field` ] }. + field : `ident` [ `binders` ] : `type` [ where `notation` ] + : `ident` [ `binders` ] [: `type` ] := `term` + +.. cmd:: Record @ident @binders {? : @sort} := {? @ident} { {*; @ident @binders : @type } } + + The first identifier :token:`ident` is the name of the defined record and :token:`sort` is its + type. The optional identifier following ``:=`` is the name of its constructor. If it is omitted, + the default name :n:`Build_@ident`, where :token:`ident` is the record name, is used. If :token:`sort` is + omitted, the default sort is :math:`\Type`. The identifiers inside the brackets are the names of + fields. For a given field :token:`ident`, its type is :n:`forall @binders, @type`. + Remark that the type of a particular identifier may depend on a previously-given identifier. Thus the + order of the fields is important. Finally, :token:`binders` are parameters of the record. + +More generally, a record may have explicitly defined (a.k.a. manifest) +fields. For instance, we might have: +:n:`Record @ident @binders : @sort := { @ident__1 : @type__1 ; @ident__2 := @term__2 ; @ident__3 : @type__3 }`. +in which case the correctness of :n:`@type__3` may rely on the instance :n:`@term__2` of :n:`@ident__2` and :n:`@term__2` may in turn depend on :n:`@ident__1`. + +.. example:: + + The set of rational numbers may be defined as: + + .. coqtop:: reset all + + Record Rat : Set := mkRat + { sign : bool + ; top : nat + ; bottom : nat + ; Rat_bottom_cond : 0 <> bottom + ; Rat_irred_cond : + forall x y z:nat, (x * y) = top /\ (x * z) = bottom -> x = 1 + }. + + Note here that the fields ``Rat_bottom_cond`` depends on the field ``bottom`` + and ``Rat_irred_cond`` depends on both ``top`` and ``bottom``. + +Let us now see the work done by the ``Record`` macro. First the macro +generates a variant type definition with just one constructor: +:n:`Variant @ident {? @binders } : @sort := @ident__0 {? @binders }`. + +To build an object of type :token:`ident`, one should provide the constructor +:n:`@ident__0` with the appropriate number of terms filling the fields of the record. + +.. example:: + + Let us define the rational :math:`1/2`: + + .. coqtop:: in + + Theorem one_two_irred : forall x y z:nat, x * y = 1 /\ x * z = 2 -> x = 1. + Admitted. + + Definition half := mkRat true 1 2 (O_S 1) one_two_irred. + Check half. + +.. FIXME: move this to the main grammar in the spec chapter + +.. _record-named-fields-grammar: + + .. productionlist:: + record_term : {| [`field_def` ; … ; `field_def`] |} + field_def : name [binders] := `record_term` + +Alternatively, the following syntax allows creating objects by using named fields, as +shown in this grammar. The fields do not have to be in any particular order, nor do they have +to be all present if the missing ones can be inferred or prompted for +(see :ref:`programs`). + +.. coqtop:: all + + Definition half' := + {| sign := true; + Rat_bottom_cond := O_S 1; + Rat_irred_cond := one_two_irred |}. + +The following settings let you control the display format for types: + +.. flag:: Printing Records + + If set, use the record syntax (shown above) as the default display format. + +You can override the display format for specified types by adding entries to these tables: + +.. table:: Printing Record @qualid + :name: Printing Record + + Specifies a set of qualids which are displayed as records. Use the + :cmd:`Add @table` and :cmd:`Remove @table` commands to update the set of qualids. + +.. table:: Printing Constructor @qualid + :name: Printing Constructor + + Specifies a set of qualids which are displayed as constructors. Use the + :cmd:`Add @table` and :cmd:`Remove @table` commands to update the set of qualids. + +This syntax can also be used for pattern matching. + +.. coqtop:: all + + Eval compute in ( + match half with + | {| sign := true; top := n |} => n + | _ => 0 + end). + +The macro generates also, when it is possible, the projection +functions for destructuring an object of type :token:`ident`. These +projection functions are given the names of the corresponding +fields. If a field is named `_` then no projection is built +for it. In our example: + +.. coqtop:: all + + Eval compute in top half. + Eval compute in bottom half. + Eval compute in Rat_bottom_cond half. + +An alternative syntax for projections based on a dot notation is +available: + +.. coqtop:: all + + Eval compute in half.(top). + +.. flag:: Printing Projections + + This flag activates the dot notation for printing. + + .. example:: + + .. coqtop:: all + + Set Printing Projections. + Check top half. + +.. FIXME: move this to the main grammar in the spec chapter + +.. _record_projections_grammar: + + .. productionlist:: terms + projection : `term` `.` ( `qualid` ) + : `term` `.` ( `qualid` `arg` … `arg` ) + : `term` `.` ( @`qualid` `term` … `term` ) + + Syntax of Record projections + +The corresponding grammar rules are given in the preceding grammar. When :token:`qualid` +denotes a projection, the syntax :n:`@term.(@qualid)` is equivalent to :n:`@qualid @term`, +the syntax :n:`@term.(@qualid {+ @arg })` to :n:`@qualid {+ @arg } @term`. +and the syntax :n:`@term.(@@qualid {+ @term })` to :n:`@@qualid {+ @term } @term`. +In each case, :token:`term` is the object projected and the +other arguments are the parameters of the inductive type. + + +.. note:: Records defined with the ``Record`` keyword are not allowed to be + recursive (references to the record's name in the type of its field + raises an error). To define recursive records, one can use the ``Inductive`` + and ``CoInductive`` keywords, resulting in an inductive or co-inductive record. + Definition of mutal inductive or co-inductive records are also allowed, as long + as all of the types in the block are records. + +.. note:: Induction schemes are automatically generated for inductive records. + Automatic generation of induction schemes for non-recursive records + defined with the ``Record`` keyword can be activated with the + ``Nonrecursive Elimination Schemes`` option (see :ref:`proofschemes-induction-principles`). + +.. note:: ``Structure`` is a synonym of the keyword ``Record``. + +.. warn:: @ident cannot be defined. + + It can happen that the definition of a projection is impossible. + This message is followed by an explanation of this impossibility. + There may be three reasons: + + #. The name :token:`ident` already exists in the environment (see :cmd:`Axiom`). + #. The body of :token:`ident` uses an incorrect elimination for + :token:`ident` (see :cmd:`Fixpoint` and :ref:`Destructors`). + #. The type of the projections :token:`ident` depends on previous + projections which themselves could not be defined. + +.. exn:: Records declared with the keyword Record or Structure cannot be recursive. + + The record name :token:`ident` appears in the type of its fields, but uses + the keyword ``Record``. Use the keyword ``Inductive`` or ``CoInductive`` instead. + +.. exn:: Cannot handle mutually (co)inductive records. + + Records cannot be defined as part of mutually inductive (or + co-inductive) definitions, whether with records only or mixed with + standard definitions. + +During the definition of the one-constructor inductive definition, all +the errors of inductive definitions, as described in Section +:ref:`gallina-inductive-definitions`, may also occur. + +.. seealso:: Coercions and records in section :ref:`coercions-classes-as-records` of the chapter devoted to coercions. + +.. _primitive_projections: + +Primitive Projections +~~~~~~~~~~~~~~~~~~~~~ + +.. flag:: Primitive Projections + + Turns on the use of primitive + projections when defining subsequent records (even through the ``Inductive`` + and ``CoInductive`` commands). Primitive projections + extended the Calculus of Inductive Constructions with a new binary + term constructor `r.(p)` representing a primitive projection `p` applied + to a record object `r` (i.e., primitive projections are always applied). + Even if the record type has parameters, these do not appear + in the internal representation of + applications of the projection, considerably reducing the sizes of + terms when manipulating parameterized records and type checking time. + On the user level, primitive projections can be used as a replacement + for the usual defined ones, although there are a few notable differences. + +.. flag:: Printing Primitive Projection Parameters + + This compatibility option reconstructs internally omitted parameters at + printing time (even though they are absent in the actual AST manipulated + by the kernel). + +Primitive Record Types +++++++++++++++++++++++ + +When the :flag:`Primitive Projections` option is on, definitions of +record types change meaning. When a type is declared with primitive +projections, its :g:`match` construct is disabled (see :ref:`primitive_projections` though). +To eliminate the (co-)inductive type, one must use its defined primitive projections. + +.. The following paragraph is quite redundant with what is above + +For compatibility, the parameters still appear to the user when +printing terms even though they are absent in the actual AST +manipulated by the kernel. This can be changed by unsetting the +:flag:`Printing Primitive Projection Parameters` flag. Further compatibility +printing can be deactivated thanks to the ``Printing Primitive Projection +Compatibility`` option which governs the printing of pattern matching +over primitive records. + +There are currently two ways to introduce primitive records types: + +#. Through the ``Record`` command, in which case the type has to be + non-recursive. The defined type enjoys eta-conversion definitionally, + that is the generalized form of surjective pairing for records: + `r` ``= Build_``\ `R` ``(``\ `r`\ ``.(``\ |p_1|\ ``) …`` `r`\ ``.(``\ |p_n|\ ``))``. + Eta-conversion allows to define dependent elimination for these types as well. +#. Through the ``Inductive`` and ``CoInductive`` commands, when + the body of the definition is a record declaration of the form + ``Build_``\ `R` ``{`` |p_1| ``:`` |t_1|\ ``; … ;`` |p_n| ``:`` |t_n| ``}``. + In this case the types can be recursive and eta-conversion is disallowed. These kind of record types + differ from their traditional versions in the sense that dependent + elimination is not available for them and only non-dependent case analysis + can be defined. + +Reduction ++++++++++ + +The basic reduction rule of a primitive projection is +|p_i| ``(Build_``\ `R` |t_1| … |t_n|\ ``)`` :math:`{\rightarrow_{\iota}}` |t_i|. +However, to take the :math:`{\delta}` flag into +account, projections can be in two states: folded or unfolded. An +unfolded primitive projection application obeys the rule above, while +the folded version delta-reduces to the unfolded version. This allows to +precisely mimic the usual unfolding rules of constants. Projections +obey the usual ``simpl`` flags of the ``Arguments`` command in particular. +There is currently no way to input unfolded primitive projections at the +user-level, and there is no way to display unfolded projections differently +from folded ones. + + +Compatibility Projections and :g:`match` +++++++++++++++++++++++++++++++++++++++++ + +To ease compatibility with ordinary record types, each primitive +projection is also defined as a ordinary constant taking parameters and +an object of the record type as arguments, and whose body is an +application of the unfolded primitive projection of the same name. These +constants are used when elaborating partial applications of the +projection. One can distinguish them from applications of the primitive +projection if the :flag:`Printing Primitive Projection Parameters` option +is off: For a primitive projection application, parameters are printed +as underscores while for the compatibility projections they are printed +as usual. + +Additionally, user-written :g:`match` constructs on primitive records +are desugared into substitution of the projections, they cannot be +printed back as :g:`match` constructs. + +Variants and extensions of :g:`match` +------------------------------------- + +.. _mult-match: + +Multiple and nested pattern matching +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +The basic version of :g:`match` allows pattern matching on simple +patterns. As an extension, multiple nested patterns or disjunction of +patterns are allowed, as in ML-like languages. + +The extension just acts as a macro that is expanded during parsing +into a sequence of match on simple patterns. Especially, a +construction defined using the extended match is generally printed +under its expanded form (see :flag:`Printing Matching`). + +.. seealso:: :ref:`extendedpatternmatching`. + +.. _if-then-else: + +Pattern-matching on boolean values: the if expression +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +For inductive types with exactly two constructors and for pattern matching +expressions that do not depend on the arguments of the constructors, it is possible +to use a ``if … then … else`` notation. For instance, the definition + +.. coqtop:: all + + Definition not (b:bool) := + match b with + | true => false + | false => true + end. + +can be alternatively written + +.. coqtop:: reset all + + Definition not (b:bool) := if b then false else true. + +More generally, for an inductive type with constructors |C_1| and |C_2|, +we have the following equivalence + +:: + + if term [dep_ret_type] then term₁ else term₂ ≡ + match term [dep_ret_type] with + | C₁ _ … _ => term₁ + | C₂ _ … _ => term₂ + end + +.. example:: + + .. coqtop:: all + + Check (fun x (H:{x=0}+{x<>0}) => + match H with + | left _ => true + | right _ => false + end). + +Notice that the printing uses the :g:`if` syntax because :g:`sumbool` is +declared as such (see :ref:`controlling-match-pp`). + +.. _irrefutable-patterns: + +Irrefutable patterns: the destructuring let variants +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Pattern-matching on terms inhabiting inductive type having only one +constructor can be alternatively written using :g:`let … in …` +constructions. There are two variants of them. + + +First destructuring let syntax +++++++++++++++++++++++++++++++ + +The expression :g:`let (`\ |ident_1|:g:`, … ,` |ident_n|\ :g:`) :=` |term_0|\ :g:`in` |term_1| performs +case analysis on |term_0| which must be in an inductive type with one +constructor having itself :math:`n` arguments. Variables |ident_1| … |ident_n| are +bound to the :math:`n` arguments of the constructor in expression |term_1|. For +instance, the definition + +.. coqtop:: reset all + + Definition fst (A B:Set) (H:A * B) := match H with + | pair x y => x + end. + +can be alternatively written + +.. coqtop:: reset all + + Definition fst (A B:Set) (p:A * B) := let (x, _) := p in x. + +Notice that reduction is different from regular :g:`let … in …` +construction since it happens only if |term_0| is in constructor form. +Otherwise, the reduction is blocked. + +The pretty-printing of a definition by matching on a irrefutable +pattern can either be done using :g:`match` or the :g:`let` construction +(see Section :ref:`controlling-match-pp`). + +If term inhabits an inductive type with one constructor `C`, we have an +equivalence between + +:: + + let (ident₁, …, identₙ) [dep_ret_type] := term in term' + +and + +:: + + match term [dep_ret_type] with + C ident₁ … identₙ => term' + end + + +Second destructuring let syntax ++++++++++++++++++++++++++++++++ + +Another destructuring let syntax is available for inductive types with +one constructor by giving an arbitrary pattern instead of just a tuple +for all the arguments. For example, the preceding example can be +written: + +.. coqtop:: reset all + + Definition fst (A B:Set) (p:A*B) := let 'pair x _ := p in x. + +This is useful to match deeper inside tuples and also to use notations +for the pattern, as the syntax :g:`let ’p := t in b` allows arbitrary +patterns to do the deconstruction. For example: + +.. coqtop:: all + + Definition deep_tuple (A:Set) (x:(A*A)*(A*A)) : A*A*A*A := + let '((a,b), (c, d)) := x in (a,b,c,d). + + Notation " x 'With' p " := (exist _ x p) (at level 20). + + Definition proj1_sig' (A:Set) (P:A->Prop) (t:{ x:A | P x }) : A := + let 'x With p := t in x. + +When printing definitions which are written using this construct it +takes precedence over let printing directives for the datatype under +consideration (see Section :ref:`controlling-match-pp`). + + +.. _controlling-match-pp: + +Controlling pretty-printing of match expressions +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +The following commands give some control over the pretty-printing +of :g:`match` expressions. + +Printing nested patterns ++++++++++++++++++++++++++ + +.. flag:: Printing Matching + + The Calculus of Inductive Constructions knows pattern matching only + over simple patterns. It is however convenient to re-factorize nested + pattern matching into a single pattern matching over a nested + pattern. + + When this option is on (default), |Coq|’s printer tries to do such + limited re-factorization. + Turning it off tells |Coq| to print only simple pattern matching problems + in the same way as the |Coq| kernel handles them. + + +Factorization of clauses with same right-hand side +++++++++++++++++++++++++++++++++++++++++++++++++++ + +.. flag:: Printing Factorizable Match Patterns + + When several patterns share the same right-hand side, it is additionally + possible to share the clauses using disjunctive patterns. Assuming that the + printing matching mode is on, this option (on by default) tells |Coq|'s + printer to try to do this kind of factorization. + +Use of a default clause ++++++++++++++++++++++++ + +.. flag:: Printing Allow Match Default Clause + + When several patterns share the same right-hand side which do not depend on the + arguments of the patterns, yet an extra factorization is possible: the + disjunction of patterns can be replaced with a `_` default clause. Assuming that + the printing matching mode and the factorization mode are on, this option (on by + default) tells |Coq|'s printer to use a default clause when relevant. + +Printing of wildcard patterns +++++++++++++++++++++++++++++++ + +.. flag:: Printing Wildcard + + Some variables in a pattern may not occur in the right-hand side of + the pattern matching clause. When this option is on (default), the + variables having no occurrences in the right-hand side of the + pattern matching clause are just printed using the wildcard symbol + “_”. + + +Printing of the elimination predicate ++++++++++++++++++++++++++++++++++++++ + +.. flag:: Printing Synth + + In most of the cases, the type of the result of a matched term is + mechanically synthesizable. Especially, if the result type does not + depend of the matched term. When this option is on (default), + the result type is not printed when |Coq| knows that it can re- + synthesize it. + + +Printing matching on irrefutable patterns +++++++++++++++++++++++++++++++++++++++++++ + +If an inductive type has just one constructor, pattern matching can be +written using the first destructuring let syntax. + +.. table:: Printing Let @qualid + :name: Printing Let + + Specifies a set of qualids for which pattern matching is displayed using a let expression. + Note that this only applies to pattern matching instances entered with :g:`match`. + It doesn't affect pattern matching explicitly entered with a destructuring + :g:`let`. + Use the :cmd:`Add @table` and :cmd:`Remove @table` commands to update this set. + + +Printing matching on booleans ++++++++++++++++++++++++++++++ + +If an inductive type is isomorphic to the boolean type, pattern matching +can be written using ``if`` … ``then`` … ``else`` …. This table controls +which types are written this way: + +.. table:: Printing If @qualid + :name: Printing If + + Specifies a set of qualids for which pattern matching is displayed using + ``if`` … ``then`` … ``else`` …. Use the :cmd:`Add @table` and :cmd:`Remove @table` + commands to update this set. + +This example emphasizes what the printing options offer. + +.. example:: + + .. coqtop:: all + + Definition snd (A B:Set) (H:A * B) := match H with + | pair x y => y + end. + + Test Printing Let for prod. + + Print snd. + + Remove Printing Let prod. + + Unset Printing Synth. + + Unset Printing Wildcard. + + Print snd. + +.. _advanced-recursive-functions: + +Advanced recursive functions +---------------------------- + +The following experimental command is available when the ``FunInd`` library has been loaded via ``Require Import FunInd``: + +.. cmd:: Function @ident {* @binder} { @decrease_annot } : @type := @term + + This command can be seen as a generalization of ``Fixpoint``. It is actually a wrapper + for several ways of defining a function *and other useful related + objects*, namely: an induction principle that reflects the recursive + structure of the function (see :tacn:`function induction`) and its fixpoint equality. + The meaning of this declaration is to define a function ident, + similarly to ``Fixpoint``. Like in ``Fixpoint``, the decreasing argument must + be given (unless the function is not recursive), but it might not + necessarily be *structurally* decreasing. The point of the {} annotation + is to name the decreasing argument *and* to describe which kind of + decreasing criteria must be used to ensure termination of recursive + calls. + +The ``Function`` construction also enjoys the ``with`` extension to define +mutually recursive definitions. However, this feature does not work +for non structurally recursive functions. + +See the documentation of functional induction (:tacn:`function induction`) +and ``Functional Scheme`` (:ref:`functional-scheme`) for how to use +the induction principle to easily reason about the function. + +Remark: To obtain the right principle, it is better to put rigid +parameters of the function as first arguments. For example it is +better to define plus like this: + +.. coqtop:: reset none + + Require Import FunInd. + +.. coqtop:: all + + Function plus (m n : nat) {struct n} : nat := + match n with + | 0 => m + | S p => S (plus m p) + end. + +than like this: + +.. coqtop:: reset all + + Function plus (n m : nat) {struct n} : nat := + match n with + | 0 => m + | S p => S (plus p m) + end. + + +*Limitations* + +|term_0| must be built as a *pure pattern matching tree* (:g:`match … with`) +with applications only *at the end* of each branch. + +Function does not support partial application of the function being +defined. Thus, the following example cannot be accepted due to the +presence of partial application of :g:`wrong` in the body of :g:`wrong`: + +.. coqtop:: all + + Fail Function wrong (C:nat) : nat := + List.hd 0 (List.map wrong (C::nil)). + +For now, dependent cases are not treated for non structurally +terminating functions. + +.. exn:: The recursive argument must be specified. + :undocumented: + +.. exn:: No argument name @ident. + :undocumented: + +.. exn:: Cannot use mutual definition with well-founded recursion or measure. + :undocumented: + +.. warn:: Cannot define graph for @ident. + + The generation of the graph relation (:n:`R_@ident`) used to compute the induction scheme of ident + raised a typing error. Only :token:`ident` is defined; the induction scheme + will not be generated. This error happens generally when: + + - the definition uses pattern matching on dependent types, + which ``Function`` cannot deal with yet. + - the definition is not a *pattern matching tree* as explained above. + +.. warn:: Cannot define principle(s) for @ident. + + The generation of the graph relation (:n:`R_@ident`) succeeded but the induction principle + could not be built. Only :token:`ident` is defined. Please report. + +.. warn:: Cannot build functional inversion principle. + + :tacn:`functional inversion` will not be available for the function. + +.. seealso:: :ref:`functional-scheme` and :tacn:`function induction` + +Depending on the ``{…}`` annotation, different definition mechanisms are +used by ``Function``. A more precise description is given below. + +.. cmdv:: Function @ident {* @binder } : @type := @term + + Defines the not recursive function :token:`ident` as if declared with + :cmd:`Definition`. Moreover the following are defined: + + + :token:`ident`\ ``_rect``, :token:`ident`\ ``_rec`` and :token:`ident`\ ``_ind``, + which reflect the pattern matching structure of :token:`term` (see :cmd:`Inductive`); + + The inductive :n:`R_@ident` corresponding to the graph of :token:`ident` (silently); + + :token:`ident`\ ``_complete`` and :token:`ident`\ ``_correct`` which + are inversion information linking the function and its graph. + +.. cmdv:: Function @ident {* @binder } { struct @ident } : @type := @term + + Defines the structural recursive function :token:`ident` as if declared + with :cmd:`Fixpoint`. Moreover the following are defined: + + + The same objects as above; + + The fixpoint equation of :token:`ident`: :n:`@ident_equation`. + +.. cmdv:: Function @ident {* @binder } { measure @term @ident } : @type := @term + Function @ident {* @binder } { wf @term @ident } : @type := @term + + Defines a recursive function by well-founded recursion. The module ``Recdef`` + of the standard library must be loaded for this feature. The ``{}`` + annotation is mandatory and must be one of the following: + + + :n:`{measure @term @ident }` with :token:`ident` being the decreasing argument + and :token:`term` being a function from type of :token:`ident` to :g:`nat` for which + value on the decreasing argument decreases (for the :g:`lt` order on :g:`nat`) + at each recursive call of :token:`term`. Parameters of the function are + bound in :token:`term`; + + :n:`{wf @term @ident }` with :token:`ident` being the decreasing argument and + :token:`term` an ordering relation on the type of :token:`ident` (i.e. of type + `T`\ :math:`_{\sf ident}` → `T`\ :math:`_{\sf ident}` → ``Prop``) for which the decreasing argument + decreases at each recursive call of :token:`term`. The order must be well-founded. + Parameters of the function are bound in :token:`term`. + + Depending on the annotation, the user is left with some proof + obligations that will be used to define the function. These proofs + are: proofs that each recursive call is actually decreasing with + respect to the given criteria, and (if the criteria is `wf`) a proof + that the ordering relation is well-founded. Once proof obligations are + discharged, the following objects are defined: + + + The same objects as with the struct; + + The lemma `ident`\ :math:`_{\sf tcc}` which collects all proof obligations in one + property; + + The lemmas `ident`\ :math:`_{\sf terminate}` and `ident`\ :math:`_{\sf F}` which is needed to be inlined + during extraction of ident. + + The way this recursive function is defined is the subject of several + papers by Yves Bertot and Antonia Balaa on the one hand, and Gilles + Barthe, Julien Forest, David Pichardie, and Vlad Rusu on the other + hand. Remark: Proof obligations are presented as several subgoals + belonging to a Lemma `ident`\ :math:`_{\sf tcc}`. + +.. _section-mechanism: + +Section mechanism +----------------- + +Sections create local contexts which can be shared across multiple definitions. + +.. example:: + + Sections are opened by the :cmd:`Section` command, and closed by :cmd:`End`. + + .. coqtop:: all + + Section s1. + + Inside a section, local parameters can be introduced using :cmd:`Variable`, + :cmd:`Hypothesis`, or :cmd:`Context` (there are also plural variants for + the first two). + + .. coqtop:: all + + Variables x y : nat. + + The command :cmd:`Let` introduces section-wide :ref:`let-in`. These definitions + won't persist when the section is closed, and all persistent definitions which + depend on `y'` will be prefixed with `let y' := y in`. + + .. coqtop:: in + + Let y' := y. + Definition x' := S x. + Definition x'' := x' + y'. + + .. coqtop:: all + + Print x'. + Print x''. + + End s1. + + Print x'. + Print x''. + + Notice the difference between the value of :g:`x'` and :g:`x''` inside section + :g:`s1` and outside. + +.. cmd:: Section @ident + + This command is used to open a section named :token:`ident`. + Section names do not need to be unique. + + +.. cmd:: End @ident + + This command closes the section named :token:`ident`. After closing of the + section, the local declarations (variables and local definitions, see :cmd:`Variable`) get + *discharged*, meaning that they stop being visible and that all global + objects defined in the section are generalized with respect to the + variables and local definitions they each depended on in the section. + + .. exn:: This is not the last opened section. + :undocumented: + +.. note:: + Most commands, like :cmd:`Hint`, :cmd:`Notation`, option management, … which + appear inside a section are canceled when the section is closed. + +.. cmd:: Variable @ident : @type + + This command links :token:`type` to the name :token:`ident` in the context of + the current section. When the current section is closed, name :token:`ident` + will be unknown and every object using this variable will be explicitly + parameterized (the variable is *discharged*). + + .. exn:: @ident already exists. + :name: @ident already exists. (Variable) + :undocumented: + + .. cmdv:: Variable {+ @ident } : @type + + Links :token:`type` to each :token:`ident`. + + .. cmdv:: Variable {+ ( {+ @ident } : @type ) } + + Declare one or more variables with various types. + + .. cmdv:: Variables {+ ( {+ @ident } : @type) } + Hypothesis {+ ( {+ @ident } : @type) } + Hypotheses {+ ( {+ @ident } : @type) } + :name: Variables; Hypothesis; Hypotheses + + These variants are synonyms of :n:`Variable {+ ( {+ @ident } : @type) }`. + +.. cmd:: Let @ident := @term + + This command binds the value :token:`term` to the name :token:`ident` in the + environment of the current section. The name :token:`ident` is accessible + only within the current section. When the section is closed, all persistent + definitions and theorems within it and depending on :token:`ident` + will be prefixed by the let-in definition :n:`let @ident := @term in`. + + .. exn:: @ident already exists. + :name: @ident already exists. (Let) + :undocumented: + + .. cmdv:: Let @ident {? @binders } {? : @type } := @term + :undocumented: + + .. cmdv:: Let Fixpoint @ident @fix_body {* with @fix_body} + :name: Let Fixpoint + :undocumented: + + .. cmdv:: Let CoFixpoint @ident @cofix_body {* with @cofix_body} + :name: Let CoFixpoint + :undocumented: + +.. cmd:: Context @binders + + Declare variables in the context of the current section, like :cmd:`Variable`, + but also allowing implicit variables, :ref:`implicit-generalization`, and + let-binders. + + .. coqdoc:: + + Context {A : Type} (a b : A). + Context `{EqDec A}. + Context (b' := b). + +.. seealso:: Section :ref:`binders`. Section :ref:`contexts` in chapter :ref:`typeclasses`. + +Module system +------------- + +The module system provides a way of packaging related elements +together, as well as a means of massive abstraction. + + .. productionlist:: modules + module_type : `qualid` + : `module_type` with Definition `qualid` := `term` + : `module_type` with Module `qualid` := `qualid` + : `qualid` `qualid` … `qualid` + : !`qualid` `qualid` … `qualid` + module_binding : ( [Import|Export] `ident` … `ident` : `module_type` ) + module_bindings : `module_binding` … `module_binding` + module_expression : `qualid` … `qualid` + : !`qualid` … `qualid` + + Syntax of modules + +In the syntax of module application, the ! prefix indicates that any +`Inline` directive in the type of the functor arguments will be ignored +(see the :cmd:`Module Type` command below). + + +.. cmd:: Module @ident + + This command is used to start an interactive module named :token:`ident`. + +.. cmdv:: Module @ident {* @module_binding} + + Starts an interactive functor with + parameters given by module_bindings. + +.. cmdv:: Module @ident : @module_type + + Starts an interactive module specifying its module type. + +.. cmdv:: Module @ident {* @module_binding} : @module_type + + Starts an interactive functor with parameters given by the list of + :token:`module_bindings`, and output module type :token:`module_type`. + +.. cmdv:: Module @ident <: {+<: @module_type } + + Starts an interactive module satisfying each :token:`module_type`. + + .. cmdv:: Module @ident {* @module_binding} <: {+<: @module_type }. + + Starts an interactive functor with parameters given by the list of + :token:`module_binding`. The output module type + is verified against each :token:`module_type`. + +.. cmdv:: Module [ Import | Export ] + + Behaves like :cmd:`Module`, but automatically imports or exports the module. + +Reserved commands inside an interactive module +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. cmd:: Include @module + + Includes the content of module in the current + interactive module. Here module can be a module expression or a module + type expression. If module is a high-order module or module type + expression then the system tries to instantiate module by the current + interactive module. + +.. cmd:: Include {+<+ @module} + + is a shortcut for the commands :n:`Include @module` for each :token:`module`. + +.. cmd:: End @ident + + This command closes the interactive module :token:`ident`. If the module type + was given the content of the module is matched against it and an error + is signaled if the matching fails. If the module is basic (is not a + functor) its components (constants, inductive types, submodules etc.) + are now available through the dot notation. + + .. exn:: No such label @ident. + :undocumented: + + .. exn:: Signature components for label @ident do not match. + :undocumented: + + .. exn:: This is not the last opened module. + :undocumented: + +.. cmd:: Module @ident := @module_expression + + This command defines the module identifier :token:`ident` to be equal + to :token:`module_expression`. + + .. cmdv:: Module @ident {* @module_binding} := @module_expression + + Defines a functor with parameters given by the list of :token:`module_binding` and body :token:`module_expression`. + + .. cmdv:: Module @ident {* @module_binding} : @module_type := @module_expression + + Defines a functor with parameters given by the list of :token:`module_binding` (possibly none), and output module type :token:`module_type`, + with body :token:`module_expression`. + + .. cmdv:: Module @ident {* @module_binding} <: {+<: @module_type} := @module_expression + + Defines a functor with parameters given by module_bindings (possibly none) with body :token:`module_expression`. + The body is checked against each :n:`@module_type__i`. + + .. cmdv:: Module @ident {* @module_binding} := {+<+ @module_expression} + + is equivalent to an interactive module where each :token:`module_expression` is included. + +.. cmd:: Module Type @ident + + This command is used to start an interactive module type :token:`ident`. + + .. cmdv:: Module Type @ident {* @module_binding} + + Starts an interactive functor type with parameters given by :token:`module_bindings`. + + +Reserved commands inside an interactive module type: +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. cmd:: Include @module + + Same as ``Include`` inside a module. + +.. cmd:: Include {+<+ @module} + + This is a shortcut for the command :n:`Include @module` for each :token:`module`. + +.. cmd:: @assumption_keyword Inline @assums + :name: Inline + + The instance of this assumption will be automatically expanded at functor application, except when + this functor application is prefixed by a ``!`` annotation. + +.. cmd:: End @ident + + This command closes the interactive module type :token:`ident`. + + .. exn:: This is not the last opened module type. + :undocumented: + +.. cmd:: Module Type @ident := @module_type + + Defines a module type :token:`ident` equal to :token:`module_type`. + + .. cmdv:: Module Type @ident {* @module_binding} := @module_type + + Defines a functor type :token:`ident` specifying functors taking arguments :token:`module_bindings` and + returning :token:`module_type`. + + .. cmdv:: Module Type @ident {* @module_binding} := {+<+ @module_type } + + is equivalent to an interactive module type were each :token:`module_type` is included. + +.. cmd:: Declare Module @ident : @module_type + + Declares a module :token:`ident` of type :token:`module_type`. + + .. cmdv:: Declare Module @ident {* @module_binding} : @module_type + + Declares a functor with parameters given by the list of :token:`module_binding` and output module type + :token:`module_type`. + +.. example:: + + Let us define a simple module. + + .. coqtop:: all + + Module M. + + Definition T := nat. + + Definition x := 0. + + Definition y : bool. + + exact true. + + Defined. + + End M. + +Inside a module one can define constants, prove theorems and do any +other things that can be done in the toplevel. Components of a closed +module can be accessed using the dot notation: + +.. coqtop:: all + + Print M.x. + +A simple module type: + +.. coqtop:: all + + Module Type SIG. + + Parameter T : Set. + + Parameter x : T. + + End SIG. + +Now we can create a new module from M, giving it a less precise +specification: the y component is dropped as well as the body of x. + +.. coqtop:: all + + Module N : SIG with Definition T := nat := M. + + Print N.T. + + Print N.x. + + Fail Print N.y. + +.. reset to remove N (undo in last coqtop block doesn't seem to do that), invisibly redefine M, SIG +.. coqtop:: none reset + + Module M. + + Definition T := nat. + + Definition x := 0. + + Definition y : bool. + + exact true. + + Defined. + + End M. + + Module Type SIG. + + Parameter T : Set. + + Parameter x : T. + + End SIG. + +The definition of :g:`N` using the module type expression :g:`SIG` with +:g:`Definition T := nat` is equivalent to the following one: + +.. coqtop:: all + + Module Type SIG'. + + Definition T : Set := nat. + + Parameter x : T. + + End SIG'. + + Module N : SIG' := M. + +If we just want to be sure that our implementation satisfies a +given module type without restricting the interface, we can use a +transparent constraint + +.. coqtop:: all + + Module P <: SIG := M. + + Print P.y. + +Now let us create a functor, i.e. a parametric module + +.. coqtop:: all + + Module Two (X Y: SIG). + + Definition T := (X.T * Y.T)%type. + + Definition x := (X.x, Y.x). + + End Two. + +and apply it to our modules and do some computations: + +.. coqtop:: all + + Module Q := Two M N. + + Eval compute in (fst Q.x + snd Q.x). + +In the end, let us define a module type with two sub-modules, sharing +some of the fields and give one of its possible implementations: + +.. coqtop:: all + + Module Type SIG2. + + Declare Module M1 : SIG. + + Module M2 <: SIG. + + Definition T := M1.T. + + Parameter x : T. + + End M2. + + End SIG2. + + Module Mod <: SIG2. + + Module M1. + + Definition T := nat. + + Definition x := 1. + + End M1. + + Module M2 := M. + + End Mod. + +Notice that ``M`` is a correct body for the component ``M2`` since its ``T`` +component is equal ``nat`` and hence ``M1.T`` as specified. + +.. note:: + + #. Modules and module types can be nested components of each other. + #. One can have sections inside a module or a module type, but not a + module or a module type inside a section. + #. Commands like :cmd:`Hint` or :cmd:`Notation` can also appear inside modules and + module types. Note that in case of a module definition like: + + :: + + Module N : SIG := M. + + or:: + + Module N : SIG. … End N. + + hints and the like valid for ``N`` are not those defined in ``M`` + (or the module body) but the ones defined in ``SIG``. + + +.. _import_qualid: + +.. cmd:: Import @qualid + + If :token:`qualid` denotes a valid basic module (i.e. its module type is a + signature), makes its components available by their short names. + + .. example:: + + .. coqtop:: reset all + + Module Mod. + + Definition T:=nat. + + Check T. + + End Mod. + + Check Mod.T. + + Fail Check T. + + Import Mod. + + Check T. + + Some features defined in modules are activated only when a module is + imported. This is for instance the case of notations (see :ref:`Notations`). + + Declarations made with the ``Local`` flag are never imported by the :cmd:`Import` + command. Such declarations are only accessible through their fully + qualified name. + + .. example:: + + .. coqtop:: all + + Module A. + + Module B. + + Local Definition T := nat. + + End B. + + End A. + + Import A. + + Fail Check B.T. + + .. cmdv:: Export @qualid + :name: Export + + When the module containing the command ``Export`` qualid + is imported, qualid is imported as well. + + .. exn:: @qualid is not a module. + :undocumented: + + .. warn:: Trying to mask the absolute name @qualid! + :undocumented: + +.. cmd:: Print Module @ident + + Prints the module type and (optionally) the body of the module :token:`ident`. + +.. cmd:: Print Module Type @ident + + Prints the module type corresponding to :token:`ident`. + +.. flag:: Short Module Printing + + This option (off by default) disables the printing of the types of fields, + leaving only their names, for the commands :cmd:`Print Module` and + :cmd:`Print Module Type`. + +Libraries and qualified names +--------------------------------- + +.. _names-of-libraries: + +Names of libraries +~~~~~~~~~~~~~~~~~~ + +The theories developed in |Coq| are stored in *library files* which are +hierarchically classified into *libraries* and *sublibraries*. To +express this hierarchy, library names are represented by qualified +identifiers qualid, i.e. as list of identifiers separated by dots (see +:ref:`gallina-identifiers`). For instance, the library file ``Mult`` of the standard +|Coq| library ``Arith`` is named ``Coq.Arith.Mult``. The identifier that starts +the name of a library is called a *library root*. All library files of +the standard library of |Coq| have the reserved root |Coq| but library +filenames based on other roots can be obtained by using |Coq| commands +(coqc, coqtop, coqdep, …) options ``-Q`` or ``-R`` (see :ref:`command-line-options`). +Also, when an interactive |Coq| session starts, a library of root ``Top`` is +started, unless option ``-top`` or ``-notop`` is set (see :ref:`command-line-options`). + +.. _qualified-names: + +Qualified names +~~~~~~~~~~~~~~~ + +Library files are modules which possibly contain submodules which +eventually contain constructions (axioms, parameters, definitions, +lemmas, theorems, remarks or facts). The *absolute name*, or *full +name*, of a construction in some library file is a qualified +identifier starting with the logical name of the library file, +followed by the sequence of submodules names encapsulating the +construction and ended by the proper name of the construction. +Typically, the absolute name ``Coq.Init.Logic.eq`` denotes Leibniz’ +equality defined in the module Logic in the sublibrary ``Init`` of the +standard library of |Coq|. + +The proper name that ends the name of a construction is the short name +(or sometimes base name) of the construction (for instance, the short +name of ``Coq.Init.Logic.eq`` is ``eq``). Any partial suffix of the absolute +name is a *partially qualified name* (e.g. ``Logic.eq`` is a partially +qualified name for ``Coq.Init.Logic.eq``). Especially, the short name of a +construction is its shortest partially qualified name. + +|Coq| does not accept two constructions (definition, theorem, …) with +the same absolute name but different constructions can have the same +short name (or even same partially qualified names as soon as the full +names are different). + +Notice that the notion of absolute, partially qualified and short +names also applies to library filenames. + +**Visibility** + +|Coq| maintains a table called the name table which maps partially qualified +names of constructions to absolute names. This table is updated by the +commands :cmd:`Require`, :cmd:`Import` and :cmd:`Export` and +also each time a new declaration is added to the context. An absolute +name is called visible from a given short or partially qualified name +when this latter name is enough to denote it. This means that the +short or partially qualified name is mapped to the absolute name in +|Coq| name table. Definitions flagged as Local are only accessible with +their fully qualified name (see :ref:`gallina-definitions`). + +It may happen that a visible name is hidden by the short name or a +qualified name of another construction. In this case, the name that +has been hidden must be referred to using one more level of +qualification. To ensure that a construction always remains +accessible, absolute names can never be hidden. + +.. example:: + + .. coqtop:: all + + Check 0. + + Definition nat := bool. + + Check 0. + + Check Datatypes.nat. + + Locate nat. + +.. seealso:: Commands :cmd:`Locate` and :cmd:`Locate Library`. + +.. _libraries-and-filesystem: + +Libraries and filesystem +~~~~~~~~~~~~~~~~~~~~~~~~ + +.. note:: The questions described here have been subject to redesign in |Coq| 8.5. + Former versions of |Coq| use the same terminology to describe slightly different things. + +Compiled files (``.vo`` and ``.vio``) store sub-libraries. In order to refer +to them inside |Coq|, a translation from file-system names to |Coq| names +is needed. In this translation, names in the file system are called +*physical* paths while |Coq| names are contrastingly called *logical* +names. + +A logical prefix Lib can be associated to a physical pathpath using +the command line option ``-Q`` `path` ``Lib``. All subfolders of path are +recursively associated to the logical path ``Lib`` extended with the +corresponding suffix coming from the physical path. For instance, the +folder ``path/fOO/Bar`` maps to ``Lib.fOO.Bar``. Subdirectories corresponding +to invalid |Coq| identifiers are skipped, and, by convention, +subdirectories named ``CVS`` or ``_darcs`` are skipped too. + +Thanks to this mechanism, ``.vo`` files are made available through the +logical name of the folder they are in, extended with their own +basename. For example, the name associated to the file +``path/fOO/Bar/File.vo`` is ``Lib.fOO.Bar.File``. The same caveat applies for +invalid identifiers. When compiling a source file, the ``.vo`` file stores +its logical name, so that an error is issued if it is loaded with the +wrong loadpath afterwards. + +Some folders have a special status and are automatically put in the +path. |Coq| commands associate automatically a logical path to files in +the repository trees rooted at the directory from where the command is +launched, ``coqlib/user-contrib/``, the directories listed in the +``$COQPATH``, ``${XDG_DATA_HOME}/coq/`` and ``${XDG_DATA_DIRS}/coq/`` +environment variables (see `XDG base directory specification +<http://standards.freedesktop.org/basedir-spec/basedir-spec-latest.html>`_) +with the same physical-to-logical translation and with an empty logical prefix. + +The command line option ``-R`` is a variant of ``-Q`` which has the strictly +same behavior regarding loadpaths, but which also makes the +corresponding ``.vo`` files available through their short names in a way +not unlike the ``Import`` command (see :ref:`here <import_qualid>`). For instance, ``-R path Lib`` +associates to the file ``/path/fOO/Bar/File.vo`` the logical name +``Lib.fOO.Bar.File``, but allows this file to be accessed through the +short names ``fOO.Bar.File,Bar.File`` and ``File``. If several files with +identical base name are present in different subdirectories of a +recursive loadpath, which of these files is found first may be system- +dependent and explicit qualification is recommended. The ``From`` argument +of the ``Require`` command can be used to bypass the implicit shortening +by providing an absolute root to the required file (see :ref:`compiled-files`). + +There also exists another independent loadpath mechanism attached to +OCaml object files (``.cmo`` or ``.cmxs``) rather than |Coq| object +files as described above. The OCaml loadpath is managed using +the option ``-I`` `path` (in the OCaml world, there is neither a +notion of logical name prefix nor a way to access files in +subdirectories of path). See the command :cmd:`Declare ML Module` in +:ref:`compiled-files` to understand the need of the OCaml loadpath. + +See :ref:`command-line-options` for a more general view over the |Coq| command +line options. + +.. _ImplicitArguments: + +Implicit arguments +------------------ + +An implicit argument of a function is an argument which can be +inferred from contextual knowledge. There are different kinds of +implicit arguments that can be considered implicit in different ways. +There are also various commands to control the setting or the +inference of implicit arguments. + + +The different kinds of implicit arguments +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Implicit arguments inferable from the knowledge of other arguments of a function +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ + +The first kind of implicit arguments covers the arguments that are +inferable from the knowledge of the type of other arguments of the +function, or of the type of the surrounding context of the +application. Especially, such implicit arguments correspond to +parameters dependent in the type of the function. Typical implicit +arguments are the type arguments in polymorphic functions. There are +several kinds of such implicit arguments. + +**Strict Implicit Arguments** + +An implicit argument can be either strict or non strict. An implicit +argument is said to be *strict* if, whatever the other arguments of the +function are, it is still inferable from the type of some other +argument. Technically, an implicit argument is strict if it +corresponds to a parameter which is not applied to a variable which +itself is another parameter of the function (since this parameter may +erase its arguments), not in the body of a match, and not itself +applied or matched against patterns (since the original form of the +argument can be lost by reduction). + +For instance, the first argument of +:: + + cons: forall A:Set, A -> list A -> list A + +in module ``List.v`` is strict because :g:`list` is an inductive type and :g:`A` +will always be inferable from the type :g:`list A` of the third argument of +:g:`cons`. Also, the first argument of :g:`cons` is strict with respect to the second one, +since the first argument is exactly the type of the second argument. +On the contrary, the second argument of a term of type +:: + + forall P:nat->Prop, forall n:nat, P n -> ex nat P + +is implicit but not strict, since it can only be inferred from the +type :g:`P n` of the third argument and if :g:`P` is, e.g., :g:`fun _ => True`, it +reduces to an expression where ``n`` does not occur any longer. The first +argument :g:`P` is implicit but not strict either because it can only be +inferred from :g:`P n` and :g:`P` is not canonically inferable from an arbitrary +:g:`n` and the normal form of :g:`P n`. Consider, e.g., that :g:`n` is :math:`0` and the third +argument has type :g:`True`, then any :g:`P` of the form +:: + + fun n => match n with 0 => True | _ => anything end + +would be a solution of the inference problem. + +**Contextual Implicit Arguments** + +An implicit argument can be *contextual* or not. An implicit argument +is said *contextual* if it can be inferred only from the knowledge of +the type of the context of the current expression. For instance, the +only argument of:: + + nil : forall A:Set, list A` + +is contextual. Similarly, both arguments of a term of type:: + + forall P:nat->Prop, forall n:nat, P n \/ n = 0 + +are contextual (moreover, :g:`n` is strict and :g:`P` is not). + +**Reversible-Pattern Implicit Arguments** + +There is another class of implicit arguments that can be reinferred +unambiguously if all the types of the remaining arguments are known. +This is the class of implicit arguments occurring in the type of +another argument in position of reversible pattern, which means it is +at the head of an application but applied only to uninstantiated +distinct variables. Such an implicit argument is called *reversible- +pattern implicit argument*. A typical example is the argument :g:`P` of +nat_rec in +:: + + nat_rec : forall P : nat -> Set, P 0 -> + (forall n : nat, P n -> P (S n)) -> forall x : nat, P x + +(:g:`P` is reinferable by abstracting over :g:`n` in the type :g:`P n`). + +See :ref:`controlling-rev-pattern-implicit-args` for the automatic declaration of reversible-pattern +implicit arguments. + +Implicit arguments inferable by resolution +++++++++++++++++++++++++++++++++++++++++++ + +This corresponds to a class of non-dependent implicit arguments that +are solved based on the structure of their type only. + + +Maximal or non maximal insertion of implicit arguments +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +In case a function is partially applied, and the next argument to be +applied is an implicit argument, two disciplines are applicable. In +the first case, the function is considered to have no arguments +furtherly: one says that the implicit argument is not maximally +inserted. In the second case, the function is considered to be +implicitly applied to the implicit arguments it is waiting for: one +says that the implicit argument is maximally inserted. + +Each implicit argument can be declared to have to be inserted maximally or non +maximally. This can be governed argument per argument by the command +:cmd:`Arguments (implicits)` or globally by the :flag:`Maximal Implicit Insertion` option. + +.. seealso:: :ref:`displaying-implicit-args`. + + +Casual use of implicit arguments +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +In a given expression, if it is clear that some argument of a function +can be inferred from the type of the other arguments, the user can +force the given argument to be guessed by replacing it by “_”. If +possible, the correct argument will be automatically generated. + +.. exn:: Cannot infer a term for this placeholder. + :name: Cannot infer a term for this placeholder. (Casual use of implicit arguments) + + |Coq| was not able to deduce an instantiation of a “_”. + +.. _declare-implicit-args: + +Declaration of implicit arguments +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +In case one wants that some arguments of a given object (constant, +inductive types, constructors, assumptions, local or not) are always +inferred by |Coq|, one may declare once and for all which are the +expected implicit arguments of this object. There are two ways to do +this, *a priori* and *a posteriori*. + + +Implicit Argument Binders ++++++++++++++++++++++++++ + +In the first setting, one wants to explicitly give the implicit +arguments of a declared object as part of its definition. To do this, +one has to surround the bindings of implicit arguments by curly +braces: + +.. coqtop:: all + + Definition id {A : Type} (x : A) : A := x. + +This automatically declares the argument A of id as a maximally +inserted implicit argument. One can then do as-if the argument was +absent in every situation but still be able to specify it if needed: + +.. coqtop:: all + + Definition compose {A B C} (g : B -> C) (f : A -> B) := fun x => g (f x). + + Goal forall A, compose id id = id (A:=A). + + +The syntax is supported in all top-level definitions: +:cmd:`Definition`, :cmd:`Fixpoint`, :cmd:`Lemma` and so on. For (co-)inductive datatype +declarations, the semantics are the following: an inductive parameter +declared as an implicit argument need not be repeated in the inductive +definition but will become implicit for the constructors of the +inductive only, not the inductive type itself. For example: + +.. coqtop:: all + + Inductive list {A : Type} : Type := + | nil : list + | cons : A -> list -> list. + + Print list. + +One can always specify the parameter if it is not uniform using the +usual implicit arguments disambiguation syntax. + + +Declaring Implicit Arguments +++++++++++++++++++++++++++++ + + + +.. cmd:: Arguments @qualid {* [ @ident ] | { @ident } | @ident } + :name: Arguments (implicits) + + This command is used to set implicit arguments *a posteriori*, + where the list of possibly bracketed :token:`ident` is a prefix of the list of + arguments of :token:`qualid` where the ones to be declared implicit are + surrounded by square brackets and the ones to be declared as maximally + inserted implicits are surrounded by curly braces. + + After the above declaration is issued, implicit arguments can just + (and have to) be skipped in any expression involving an application + of :token:`qualid`. + +.. cmd:: Arguments @qualid : clear implicits + + This command clears implicit arguments. + +.. cmdv:: Global Arguments @qualid {* [ @ident ] | { @ident } | @ident } + + This command is used to recompute the implicit arguments of + :token:`qualid` after ending of the current section if any, enforcing the + implicit arguments known from inside the section to be the ones + declared by the command. + +.. cmdv:: Local Arguments @qualid {* [ @ident ] | { @ident } | @ident } + + When in a module, tell not to activate the + implicit arguments of :token:`qualid` declared by this command to contexts that + require the module. + +.. cmdv:: {? Global | Local } Arguments @qualid {*, {+ [ @ident ] | { @ident } | @ident } } + + For names of constants, inductive types, + constructors, lemmas which can only be applied to a fixed number of + arguments (this excludes for instance constants whose type is + polymorphic), multiple implicit arguments declarations can be given. + Depending on the number of arguments qualid is applied to in practice, + the longest applicable list of implicit arguments is used to select + which implicit arguments are inserted. For printing, the omitted + arguments are the ones of the longest list of implicit arguments of + the sequence. + +.. example:: + + .. coqtop:: reset all + + Inductive list (A : Type) : Type := + | nil : list A + | cons : A -> list A -> list A. + + Check (cons nat 3 (nil nat)). + + Arguments cons [A] _ _. + + Arguments nil {A}. + + Check (cons 3 nil). + + Fixpoint map (A B : Type) (f : A -> B) (l : list A) : list B := + match l with nil => nil | cons a t => cons (f a) (map A B f t) end. + + Fixpoint length (A : Type) (l : list A) : nat := + match l with nil => 0 | cons _ m => S (length A m) end. + + Arguments map [A B] f l. + + Arguments length {A} l. (* A has to be maximally inserted *) + + Check (fun l:list (list nat) => map length l). + + Arguments map [A B] f l, [A] B f l, A B f l. + + Check (fun l => map length l = map (list nat) nat length l). + +.. note:: + To know which are the implicit arguments of an object, use the + command :cmd:`Print Implicit` (see :ref:`displaying-implicit-args`). + +.. warn:: Argument number @num is a trailing implicit so must be maximal. + + For instance in + + .. coqtop:: all warn + + Arguments prod _ [_]. + +Automatic declaration of implicit arguments +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. cmd:: Arguments @qualid : default implicits + + This command tells |Coq| to automatically detect what are the implicit arguments of a + defined object. + + The auto-detection is governed by options telling if strict, + contextual, or reversible-pattern implicit arguments must be + considered or not (see :ref:`controlling-strict-implicit-args`, :ref:`controlling-strict-implicit-args`, + :ref:`controlling-rev-pattern-implicit-args`, and also :ref:`controlling-insertion-implicit-args`). + + .. cmdv:: Global Arguments @qualid : default implicits + + Tell to recompute the + implicit arguments of qualid after ending of the current section if + any. + + .. cmdv:: Local Arguments @qualid : default implicits + + When in a module, tell not to activate the implicit arguments of :token:`qualid` computed by this + declaration to contexts that requires the module. + +.. example:: + + .. coqtop:: reset all + + Inductive list (A:Set) : Set := + | nil : list A + | cons : A -> list A -> list A. + + Arguments cons : default implicits. + + Print Implicit cons. + + Arguments nil : default implicits. + + Print Implicit nil. + + Set Contextual Implicit. + + Arguments nil : default implicits. + + Print Implicit nil. + +The computation of implicit arguments takes account of the unfolding +of constants. For instance, the variable ``p`` below has type +``(Transitivity R)`` which is reducible to +``forall x,y:U, R x y -> forall z:U, R y z -> R x z``. As the variables ``x``, ``y`` and ``z`` +appear strictly in the body of the type, they are implicit. + +.. coqtop:: all + + Parameter X : Type. + + Definition Relation := X -> X -> Prop. + + Definition Transitivity (R:Relation) := forall x y:X, R x y -> forall z:X, R y z -> R x z. + + Parameters (R : Relation) (p : Transitivity R). + + Arguments p : default implicits. + + Print p. + + Print Implicit p. + + Parameters (a b c : X) (r1 : R a b) (r2 : R b c). + + Check (p r1 r2). + + +Mode for automatic declaration of implicit arguments +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. flag:: Implicit Arguments + + This option (off by default) allows to systematically declare implicit + the arguments detectable as such. Auto-detection of implicit arguments is + governed by options controlling whether strict and contextual implicit + arguments have to be considered or not. + +.. _controlling-strict-implicit-args: + +Controlling strict implicit arguments +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. flag:: Strict Implicit + + When the mode for automatic declaration of implicit arguments is on, + the default is to automatically set implicit only the strict implicit + arguments plus, for historical reasons, a small subset of the non-strict + implicit arguments. To relax this constraint and to set + implicit all non strict implicit arguments by default, you can turn this + option off. + +.. flag:: Strongly Strict Implicit + + Use this option (off by default) to capture exactly the strict implicit + arguments and no more than the strict implicit arguments. + +.. _controlling-contextual-implicit-args: + +Controlling contextual implicit arguments +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. flag:: Contextual Implicit + + By default, |Coq| does not automatically set implicit the contextual + implicit arguments. You can turn this option on to tell |Coq| to also + infer contextual implicit argument. + +.. _controlling-rev-pattern-implicit-args: + +Controlling reversible-pattern implicit arguments +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. flag:: Reversible Pattern Implicit + + By default, |Coq| does not automatically set implicit the reversible-pattern + implicit arguments. You can turn this option on to tell |Coq| to also infer + reversible-pattern implicit argument. + +.. _controlling-insertion-implicit-args: + +Controlling the insertion of implicit arguments not followed by explicit arguments +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. flag:: Maximal Implicit Insertion + + Assuming the implicit argument mode is on, this option (off by default) + declares implicit arguments to be automatically inserted when a + function is partially applied and the next argument of the function is + an implicit one. + +.. _explicit-applications: + +Explicit applications +~~~~~~~~~~~~~~~~~~~~~ + +In presence of non-strict or contextual argument, or in presence of +partial applications, the synthesis of implicit arguments may fail, so +one may have to give explicitly certain implicit arguments of an +application. The syntax for this is :n:`(@ident := @term)` where :token:`ident` is the +name of the implicit argument and term is its corresponding explicit +term. Alternatively, one can locally deactivate the hiding of implicit +arguments of a function by using the notation :n:`@qualid {+ @term }`. +This syntax extension is given in the following grammar: + +.. _explicit_app_grammar: + + .. productionlist:: explicit_apps + term : @ `qualid` `term` … `term` + : @ `qualid` + : `qualid` `argument` … `argument` + argument : `term` + : (`ident` := `term`) + + Syntax for explicitly giving implicit arguments + +.. example:: (continued) + + .. coqtop:: all + + Check (p r1 (z:=c)). + + Check (p (x:=a) (y:=b) r1 (z:=c) r2). + + +Renaming implicit arguments +~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. cmd:: Arguments @qualid {* @name} : @rename + + This command is used to redefine the names of implicit arguments. + +With the assert flag, ``Arguments`` can be used to assert that a given +object has the expected number of arguments and that these arguments +are named as expected. + +.. example:: (continued) + + .. coqtop:: all + + Arguments p [s t] _ [u] _: rename. + + Check (p r1 (u:=c)). + + Check (p (s:=a) (t:=b) r1 (u:=c) r2). + + Fail Arguments p [s t] _ [w] _ : assert. + +.. _displaying-implicit-args: + +Displaying what the implicit arguments are +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. cmd:: Print Implicit @qualid + + Use this command to display the implicit arguments associated to an object, + and to know if each of them is to be used maximally or not. + + +Explicit displaying of implicit arguments for pretty-printing +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. flag:: Printing Implicit + + By default, the basic pretty-printing rules hide the inferable implicit + arguments of an application. Turn this option on to force printing all + implicit arguments. + +.. flag:: Printing Implicit Defensive + + By default, the basic pretty-printing rules display the implicit + arguments that are not detected as strict implicit arguments. This + “defensive” mode can quickly make the display cumbersome so this can + be deactivated by turning this option off. + +.. seealso:: :flag:`Printing All`. + +Interaction with subtyping +~~~~~~~~~~~~~~~~~~~~~~~~~~ + +When an implicit argument can be inferred from the type of more than +one of the other arguments, then only the type of the first of these +arguments is taken into account, and not an upper type of all of them. +As a consequence, the inference of the implicit argument of “=” fails +in + +.. coqtop:: all + + Fail Check nat = Prop. + +but succeeds in + +.. coqtop:: all + + Check Prop = nat. + + +Deactivation of implicit arguments for parsing +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. flag:: Parsing Explicit + + Turning this option on (it is off by default) deactivates the use of implicit arguments. + + In this case, all arguments of constants, inductive types, + constructors, etc, including the arguments declared as implicit, have + to be given as if no arguments were implicit. By symmetry, this also + affects printing. + +Canonical structures +~~~~~~~~~~~~~~~~~~~~ + +A canonical structure is an instance of a record/structure type that +can be used to solve unification problems involving a projection +applied to an unknown structure instance (an implicit argument) and a +value. The complete documentation of canonical structures can be found +in :ref:`canonicalstructures`; here only a simple example is given. + +.. cmd:: Canonical {? Structure } @qualid + + This command declares :token:`qualid` as a canonical instance of a + structure (a record). + + Assume that :token:`qualid` denotes an object ``(Build_struct`` |c_1| … |c_n| ``)`` in the + structure :g:`struct` of which the fields are |x_1|, …, |x_n|. + Then, each time an equation of the form ``(``\ |x_i| ``_)`` |eq_beta_delta_iota_zeta| |c_i| has to be + solved during the type checking process, :token:`qualid` is used as a solution. + Otherwise said, :token:`qualid` is canonically used to extend the field |c_i| + into a complete structure built on |c_i|. + + Canonical structures are particularly useful when mixed with coercions + and strict implicit arguments. + + .. example:: + + Here is an example. + + .. coqtop:: all + + Require Import Relations. + + Require Import EqNat. + + Set Implicit Arguments. + + Unset Strict Implicit. + + Structure Setoid : Type := {Carrier :> Set; Equal : relation Carrier; + Prf_equiv : equivalence Carrier Equal}. + + Definition is_law (A B:Setoid) (f:A -> B) := forall x y:A, Equal x y -> Equal (f x) (f y). + + Axiom eq_nat_equiv : equivalence nat eq_nat. + + Definition nat_setoid : Setoid := Build_Setoid eq_nat_equiv. + + Canonical nat_setoid. + + Thanks to :g:`nat_setoid` declared as canonical, the implicit arguments :g:`A` + and :g:`B` can be synthesized in the next statement. + + .. coqtop:: all abort + + Lemma is_law_S : is_law S. + + .. note:: + If a same field occurs in several canonical structures, then + only the structure declared first as canonical is considered. + + .. cmdv:: Canonical {? Structure } @ident {? : @type } := @term + + This is equivalent to a regular definition of :token:`ident` followed by the + declaration :n:`Canonical @ident`. + +.. cmd:: Print Canonical Projections + + This displays the list of global names that are components of some + canonical structure. For each of them, the canonical structure of + which it is a projection is indicated. + + .. example:: + + For instance, the above example gives the following output: + + .. coqtop:: all + + Print Canonical Projections. + + +Implicit types of variables +~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +It is possible to bind variable names to a given type (e.g. in a +development using arithmetic, it may be convenient to bind the names :g:`n` +or :g:`m` to the type :g:`nat` of natural numbers). + +.. cmd:: Implicit Types {+ @ident } : @type + + The effect of the command is to automatically set the type of bound + variables starting with :token:`ident` (either :token:`ident` itself or + :token:`ident` followed by one or more single quotes, underscore or + digits) to be :token:`type` (unless the bound variable is already declared + with an explicit type in which case, this latter type is considered). + +.. example:: + + .. coqtop:: all + + Require Import List. + + Implicit Types m n : nat. + + Lemma cons_inj_nat : forall m n l, n :: l = m :: l -> n = m. + Proof. intros m n. Abort. + + Lemma cons_inj_bool : forall (m n:bool) l, n :: l = m :: l -> n = m. + Abort. + +.. cmdv:: Implicit Type @ident : @type + + This is useful for declaring the implicit type of a single variable. + +.. cmdv:: Implicit Types {+ ( {+ @ident } : @type ) } + + Adds blocks of implicit types with different specifications. + +.. _implicit-generalization: + +Implicit generalization +~~~~~~~~~~~~~~~~~~~~~~~ + +.. index:: `{ } +.. index:: `( ) + +Implicit generalization is an automatic elaboration of a statement +with free variables into a closed statement where these variables are +quantified explicitly. Implicit generalization is done inside binders +starting with a \` and terms delimited by \`{ } and \`( ), always +introducing maximally inserted implicit arguments for the generalized +variables. Inside implicit generalization delimiters, free variables +in the current context are automatically quantified using a product or +a lambda abstraction to generate a closed term. In the following +statement for example, the variables n and m are automatically +generalized and become explicit arguments of the lemma as we are using +\`( ): + +.. coqtop:: all + + Generalizable All Variables. + + Lemma nat_comm : `(n = n + 0). + +One can control the set of generalizable identifiers with +the ``Generalizable`` vernacular command to avoid unexpected +generalizations when mistyping identifiers. There are several commands +that specify which variables should be generalizable. + +.. cmd:: Generalizable All Variables + + All variables are candidate for + generalization if they appear free in the context under a + generalization delimiter. This may result in confusing errors in case + of typos. In such cases, the context will probably contain some + unexpected generalized variable. + +.. cmd:: Generalizable No Variables + + Disable implicit generalization entirely. This is the default behavior. + +.. cmd:: Generalizable (Variable | Variables) {+ @ident } + + Allow generalization of the given identifiers only. Calling this command multiple times + adds to the allowed identifiers. + +.. cmd:: Global Generalizable + + Allows exporting the choice of generalizable variables. + +One can also use implicit generalization for binders, in which case +the generalized variables are added as binders and set maximally +implicit. + +.. coqtop:: all + + Definition id `(x : A) : A := x. + + Print id. + +The generalizing binders \`{ } and \`( ) work similarly to their +explicit counterparts, only binding the generalized variables +implicitly, as maximally-inserted arguments. In these binders, the +binding name for the bound object is optional, whereas the type is +mandatory, dually to regular binders. + +.. _Coercions: + +Coercions +--------- + +Coercions can be used to implicitly inject terms from one *class* in +which they reside into another one. A *class* is either a sort +(denoted by the keyword ``Sortclass``), a product type (denoted by the +keyword ``Funclass``), or a type constructor (denoted by its name), e.g. +an inductive type or any constant with a type of the form +``forall (`` |x_1| : |A_1| ) … ``(``\ |x_n| : |A_n|\ ``)``, `s` where `s` is a sort. + +Then the user is able to apply an object that is not a function, but +can be coerced to a function, and more generally to consider that a +term of type ``A`` is of type ``B`` provided that there is a declared coercion +between ``A`` and ``B``. + +More details and examples, and a description of the commands related +to coercions are provided in :ref:`implicitcoercions`. + +.. _printing_constructions_full: + +Printing constructions in full +------------------------------ + +.. flag:: Printing All + + Coercions, implicit arguments, the type of pattern matching, but also + notations (see :ref:`syntaxextensionsandinterpretationscopes`) can obfuscate the behavior of some + tactics (typically the tactics applying to occurrences of subterms are + sensitive to the implicit arguments). Turning this option on + deactivates all high-level printing features such as coercions, + implicit arguments, returned type of pattern matching, notations and + various syntactic sugar for pattern matching or record projections. + Otherwise said, :flag:`Printing All` includes the effects of the options + :flag:`Printing Implicit`, :flag:`Printing Coercions`, :flag:`Printing Synth`, + :flag:`Printing Projections`, and :flag:`Printing Notations`. To reactivate + the high-level printing features, use the command ``Unset Printing All``. + +.. _printing-universes: + +Printing universes +------------------ + +.. flag:: Printing Universes + + Turn this option on to activate the display of the actual level of each + occurrence of :g:`Type`. See :ref:`Sorts` for details. This wizard option, in + combination with :flag:`Printing All` can help to diagnose failures to unify + terms apparently identical but internally different in the Calculus of Inductive + Constructions. + +.. cmd:: Print {? Sorted} Universes + :name: Print Universes + + This command can be used to print the constraints on the internal level + of the occurrences of :math:`\Type` (see :ref:`Sorts`). + + If the optional ``Sorted`` option is given, each universe will be made + equivalent to a numbered label reflecting its level (with a linear + ordering) in the universe hierarchy. + + .. cmdv:: Print {? Sorted} Universes @string + + This variant accepts an optional output filename. + + If :token:`string` ends in ``.dot`` or ``.gv``, the constraints are printed in the DOT + language, and can be processed by Graphviz tools. The format is + unspecified if `string` doesn’t end in ``.dot`` or ``.gv``. + +.. cmdv:: Print Universes Subgraph(@names) + + Prints the graph restricted to the requested names (adjusting + constraints to preserve the implied transitive constraints between + kept universes). + +.. _existential-variables: + +Existential variables +--------------------- + +|Coq| terms can include existential variables which represents unknown +subterms to eventually be replaced by actual subterms. + +Existential variables are generated in place of unsolvable implicit +arguments or “_” placeholders when using commands such as ``Check`` (see +Section :ref:`requests-to-the-environment`) or when using tactics such as +:tacn:`refine`, as well as in place of unsolvable instances when using +tactics such that :tacn:`eapply`. An existential +variable is defined in a context, which is the context of variables of +the placeholder which generated the existential variable, and a type, +which is the expected type of the placeholder. + +As a consequence of typing constraints, existential variables can be +duplicated in such a way that they possibly appear in different +contexts than their defining context. Thus, any occurrence of a given +existential variable comes with an instance of its original context. +In the simple case, when an existential variable denotes the +placeholder which generated it, or is used in the same context as the +one in which it was generated, the context is not displayed and the +existential variable is represented by “?” followed by an identifier. + +.. coqtop:: all + + Parameter identity : forall (X:Set), X -> X. + + Check identity _ _. + + Check identity _ (fun x => _). + +In the general case, when an existential variable :n:`?@ident` appears +outside of its context of definition, its instance, written under the +form :n:`{ {*; @ident := @term} }` is appending to its name, indicating +how the variables of its defining context are instantiated. +The variables of the context of the existential variables which are +instantiated by themselves are not written, unless the flag :flag:`Printing Existential Instances` +is on (see Section :ref:`explicit-display-existentials`), and this is why an +existential variable used in the same context as its context of definition is written with no instance. + +.. coqtop:: all + + Check (fun x y => _) 0 1. + + Set Printing Existential Instances. + + Check (fun x y => _) 0 1. + +Existential variables can be named by the user upon creation using +the syntax :n:`?[@ident]`. This is useful when the existential +variable needs to be explicitly handled later in the script (e.g. +with a named-goal selector, see :ref:`goal-selectors`). + +.. _explicit-display-existentials: + +Explicit displaying of existential instances for pretty-printing +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. flag:: Printing Existential Instances + + This option (off by default) activates the full display of how the + context of an existential variable is instantiated at each of the + occurrences of the existential variable. + +.. _tactics-in-terms: + +Solving existential variables using tactics +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Instead of letting the unification engine try to solve an existential +variable by itself, one can also provide an explicit hole together +with a tactic to solve it. Using the syntax ``ltac:(``\ `tacexpr`\ ``)``, the user +can put a tactic anywhere a term is expected. The order of resolution +is not specified and is implementation-dependent. The inner tactic may +use any variable defined in its scope, including repeated alternations +between variables introduced by term binding as well as those +introduced by tactic binding. The expression `tacexpr` can be any tactic +expression as described in :ref:`ltac`. + +.. coqtop:: all + + Definition foo (x : nat) : nat := ltac:(exact x). + +This construction is useful when one wants to define complicated terms +using highly automated tactics without resorting to writing the proof-term +by means of the interactive proof engine. + +.. _primitive-integers: + +Primitive Integers +-------------------------------- + +The language of terms features 63-bit machine integers as values. The type of +such a value is *axiomatized*; it is declared through the following sentence +(excerpt from the :g:`Int63` module): + +.. coqdoc:: + + Primitive int := #int63_type. + +This type is equipped with a few operators, that must be similarly declared. +For instance, equality of two primitive integers can be decided using the :g:`Int63.eqb` function, +declared and specified as follows: + +.. coqdoc:: + + Primitive eqb := #int63_eq. + Notation "m '==' n" := (eqb m n) (at level 70, no associativity) : int63_scope. + + Axiom eqb_correct : forall i j, (i == j)%int63 = true -> i = j. + +The complete set of such operators can be obtained looking at the :g:`Int63` module. + +These primitive declarations are regular axioms. As such, they must be trusted and are listed by the +:g:`Print Assumptions` command, as in the following example. + +.. coqtop:: in reset + + From Coq Require Import Int63. + Lemma one_minus_one_is_zero : (1 - 1 = 0)%int63. + Proof. apply eqb_correct; vm_compute; reflexivity. Qed. + +.. coqtop:: all + + Print Assumptions one_minus_one_is_zero. + +The reduction machines (:tacn:`vm_compute`, :tacn:`native_compute`) implement +dedicated, efficient, rules to reduce the applications of these primitive +operations. + +These primitives, when extracted to OCaml (see :ref:`extraction`), are mapped to +types and functions of a :g:`Uint63` module. Said module is not produced by +extraction. Instead, it has to be provided by the user (if they want to compile +or execute the extracted code). For instance, an implementation of this module +can be taken from the kernel of Coq. diff --git a/doc/sphinx/language/gallina-specification-language.rst b/doc/sphinx/language/gallina-specification-language.rst new file mode 100644 index 0000000000..5a1af9f9fa --- /dev/null +++ b/doc/sphinx/language/gallina-specification-language.rst @@ -0,0 +1,1545 @@ +.. _gallinaspecificationlanguage: + +------------------------------------ + The Gallina specification language +------------------------------------ + +This chapter describes Gallina, the specification language of Coq. It allows +developing mathematical theories and to prove specifications of programs. The +theories are built from axioms, hypotheses, parameters, lemmas, theorems and +definitions of constants, functions, predicates and sets. The syntax of logical +objects involved in theories is described in Section :ref:`term`. The +language of commands, called *The Vernacular* is described in Section +:ref:`vernacular`. + +In Coq, logical objects are typed to ensure their logical correctness. The +rules implemented by the typing algorithm are described in Chapter :ref:`calculusofinductiveconstructions`. + + +About the grammars in the manual +================================ + +Grammars are presented in Backus-Naur form (BNF). Terminal symbols are +set in black ``typewriter font``. In addition, there are special notations for +regular expressions. + +An expression enclosed in square brackets ``[…]`` means at most one +occurrence of this expression (this corresponds to an optional +component). + +The notation “``entry sep … sep entry``” stands for a non empty sequence +of expressions parsed by entry and separated by the literal “``sep``” [1]_. + +Similarly, the notation “``entry … entry``” stands for a non empty +sequence of expressions parsed by the “``entry``” entry, without any +separator between. + +At the end, the notation “``[entry sep … sep entry]``” stands for a +possibly empty sequence of expressions parsed by the “``entry``” entry, +separated by the literal “``sep``”. + +.. _lexical-conventions: + +Lexical conventions +=================== + +Blanks + Space, newline and horizontal tabulation are considered as blanks. + Blanks are ignored but they separate tokens. + +Comments + Comments in Coq are enclosed between ``(*`` and ``*)``, and can be nested. + They can contain any character. However, :token:`string` literals must be + correctly closed. Comments are treated as blanks. + +Identifiers and access identifiers + Identifiers, written :token:`ident`, are sequences of letters, digits, ``_`` and + ``'``, that do not start with a digit or ``'``. That is, they are + recognized by the following lexical class: + + .. productionlist:: coq + first_letter : a..z ∣ A..Z ∣ _ ∣ unicode-letter + subsequent_letter : a..z ∣ A..Z ∣ 0..9 ∣ _ ∣ ' ∣ unicode-letter ∣ unicode-id-part + ident : `first_letter`[`subsequent_letter`…`subsequent_letter`] + access_ident : .`ident` + + All characters are meaningful. In particular, identifiers are case-sensitive. + The entry ``unicode-letter`` non-exhaustively includes Latin, + Greek, Gothic, Cyrillic, Arabic, Hebrew, Georgian, Hangul, Hiragana + and Katakana characters, CJK ideographs, mathematical letter-like + symbols, hyphens, non-breaking space, … The entry ``unicode-id-part`` + non-exhaustively includes symbols for prime letters and subscripts. + + Access identifiers, written :token:`access_ident`, are identifiers prefixed by + `.` (dot) without blank. They are used in the syntax of qualified + identifiers. + +Numerals + Numerals are sequences of digits with a potential fractional part + and exponent. Integers are numerals without fractional nor exponent + part and optionally preceded by a minus sign. Underscores ``_`` can + be used as comments in numerals. + + .. productionlist:: coq + digit : 0..9 + num : `digit`…`digit` + integer : [-]`num` + dot : . + exp : e | E + sign : + | - + numeral : `num`[`dot` `num`][`exp`[`sign`]`num`] + +Strings + Strings are delimited by ``"`` (double quote), and enclose a sequence of + any characters different from ``"`` or the sequence ``""`` to denote the + double quote character. In grammars, the entry for quoted strings is + :production:`string`. + +Keywords + The following identifiers are reserved keywords, and cannot be + employed otherwise:: + + _ as at cofix else end exists exists2 fix for + forall fun if IF in let match mod return + SProp Prop Set Type then using where with + +Special tokens + The following sequences of characters are special tokens:: + + ! % & && ( () ) * + ++ , - -> . .( .. + / /\ : :: :< := :> ; < <- <-> <: <= <> = + => =_D > >-> >= ? ?= @ [ \/ ] ^ { | |- + || } ~ #[ + + Lexical ambiguities are resolved according to the “longest match” + rule: when a sequence of non alphanumerical characters can be + decomposed into several different ways, then the first token is the + longest possible one (among all tokens defined at this moment), and so + on. + +.. _term: + +Terms +===== + +Syntax of terms +--------------- + +The following grammars describe the basic syntax of the terms of the +*Calculus of Inductive Constructions* (also called Cic). The formal +presentation of Cic is given in Chapter :ref:`calculusofinductiveconstructions`. Extensions of this syntax +are given in Chapter :ref:`extensionsofgallina`. How to customize the syntax +is described in Chapter :ref:`syntaxextensionsandinterpretationscopes`. + +.. productionlist:: coq + term : forall `binders` , `term` + : fun `binders` => `term` + : fix `fix_bodies` + : cofix `cofix_bodies` + : let `ident` [`binders`] [: `term`] := `term` in `term` + : let fix `fix_body` in `term` + : let cofix `cofix_body` in `term` + : let ( [`name` , … , `name`] ) [`dep_ret_type`] := `term` in `term` + : let ' `pattern` [in `term`] := `term` [`return_type`] in `term` + : if `term` [`dep_ret_type`] then `term` else `term` + : `term` : `term` + : `term` <: `term` + : `term` :> + : `term` -> `term` + : `term` `arg` … `arg` + : @ `qualid` [`term` … `term`] + : `term` % `ident` + : match `match_item` , … , `match_item` [`return_type`] with + : [[|] `equation` | … | `equation`] end + : `qualid` + : `sort` + : `num` + : _ + : ( `term` ) + arg : `term` + : ( `ident` := `term` ) + binders : `binder` … `binder` + binder : `name` + : ( `name` … `name` : `term` ) + : ( `name` [: `term`] := `term` ) + : ' `pattern` + name : `ident` | _ + qualid : `ident` | `qualid` `access_ident` + sort : SProp | Prop | Set | Type + fix_bodies : `fix_body` + : `fix_body` with `fix_body` with … with `fix_body` for `ident` + cofix_bodies : `cofix_body` + : `cofix_body` with `cofix_body` with … with `cofix_body` for `ident` + fix_body : `ident` `binders` [`annotation`] [: `term`] := `term` + cofix_body : `ident` [`binders`] [: `term`] := `term` + annotation : { struct `ident` } + match_item : `term` [as `name`] [in `qualid` [`pattern` … `pattern`]] + dep_ret_type : [as `name`] `return_type` + return_type : return `term` + equation : `mult_pattern` | … | `mult_pattern` => `term` + mult_pattern : `pattern` , … , `pattern` + pattern : `qualid` `pattern` … `pattern` + : @ `qualid` `pattern` … `pattern` + : `pattern` as `ident` + : `pattern` % `ident` + : `qualid` + : _ + : `num` + : ( `or_pattern` , … , `or_pattern` ) + or_pattern : `pattern` | … | `pattern` + + +Types +----- + +Coq terms are typed. Coq types are recognized by the same syntactic +class as :token:`term`. We denote by :production:`type` the semantic subclass +of types inside the syntactic class :token:`term`. + +.. _gallina-identifiers: + +Qualified identifiers and simple identifiers +-------------------------------------------- + +*Qualified identifiers* (:token:`qualid`) denote *global constants* +(definitions, lemmas, theorems, remarks or facts), *global variables* +(parameters or axioms), *inductive types* or *constructors of inductive +types*. *Simple identifiers* (or shortly :token:`ident`) are a syntactic subset +of qualified identifiers. Identifiers may also denote *local variables*, +while qualified identifiers do not. + +Numerals +-------- + +Numerals have no definite semantics in the calculus. They are mere +notations that can be bound to objects through the notation mechanism +(see Chapter :ref:`syntaxextensionsandinterpretationscopes` for details). +Initially, numerals are bound to Peano’s representation of natural +numbers (see :ref:`datatypes`). + +.. note:: + + Negative integers are not at the same level as :token:`num`, for this + would make precedence unnatural. + +.. index:: + single: Set (sort) + single: SProp + single: Prop + single: Type + +Sorts +----- + +There are four sorts :g:`SProp`, :g:`Prop`, :g:`Set` and :g:`Type`. + +- :g:`SProp` is the universe of *definitionally irrelevant + propositions* (also called *strict propositions*). + +- :g:`Prop` is the universe of *logical propositions*. The logical propositions + themselves are typing the proofs. We denote propositions by :production:`form`. + This constitutes a semantic subclass of the syntactic class :token:`term`. + +- :g:`Set` is the universe of *program types* or *specifications*. The + specifications themselves are typing the programs. We denote + specifications by :production:`specif`. This constitutes a semantic subclass of + the syntactic class :token:`term`. + +- :g:`Type` is the type of sorts. + +More on sorts can be found in Section :ref:`sorts`. + +.. _binders: + +Binders +------- + +Various constructions such as :g:`fun`, :g:`forall`, :g:`fix` and :g:`cofix` +*bind* variables. A binding is represented by an identifier. If the binding +variable is not used in the expression, the identifier can be replaced by the +symbol :g:`_`. When the type of a bound variable cannot be synthesized by the +system, it can be specified with the notation :n:`(@ident : @type)`. There is also +a notation for a sequence of binding variables sharing the same type: +:n:`({+ @ident} : @type)`. A +binder can also be any pattern prefixed by a quote, e.g. :g:`'(x,y)`. + +Some constructions allow the binding of a variable to value. This is +called a “let-binder”. The entry :token:`binder` of the grammar accepts +either an assumption binder as defined above or a let-binder. The notation in +the latter case is :n:`(@ident := @term)`. In a let-binder, only one +variable can be introduced at the same time. It is also possible to give +the type of the variable as follows: +:n:`(@ident : @type := @term)`. + +Lists of :token:`binder` are allowed. In the case of :g:`fun` and :g:`forall`, +it is intended that at least one binder of the list is an assumption otherwise +fun and forall gets identical. Moreover, parentheses can be omitted in +the case of a single sequence of bindings sharing the same type (e.g.: +:g:`fun (x y z : A) => t` can be shortened in :g:`fun x y z : A => t`). + +.. index:: fun ... => ... + +Abstractions +------------ + +The expression :n:`fun @ident : @type => @term` defines the +*abstraction* of the variable :token:`ident`, of type :token:`type`, over the term +:token:`term`. It denotes a function of the variable :token:`ident` that evaluates to +the expression :token:`term` (e.g. :g:`fun x : A => x` denotes the identity +function on type :g:`A`). The keyword :g:`fun` can be followed by several +binders as given in Section :ref:`binders`. Functions over +several variables are equivalent to an iteration of one-variable +functions. For instance the expression +“fun :token:`ident`\ :math:`_{1}` … :token:`ident`\ :math:`_{n}` +: :token:`type` => :token:`term`” +denotes the same function as “ fun :token:`ident`\ +:math:`_{1}` : :token:`type` => … +fun :token:`ident`\ :math:`_{n}` : :token:`type` => :token:`term`”. If +a let-binder occurs in +the list of binders, it is expanded to a let-in definition (see +Section :ref:`let-in`). + +.. index:: forall + +Products +-------- + +The expression :n:`forall @ident : @type, @term` denotes the +*product* of the variable :token:`ident` of type :token:`type`, over the term :token:`term`. +As for abstractions, :g:`forall` is followed by a binder list, and products +over several variables are equivalent to an iteration of one-variable +products. Note that :token:`term` is intended to be a type. + +If the variable :token:`ident` occurs in :token:`term`, the product is called +*dependent product*. The intention behind a dependent product +:g:`forall x : A, B` is twofold. It denotes either +the universal quantification of the variable :g:`x` of type :g:`A` +in the proposition :g:`B` or the functional dependent product from +:g:`A` to :g:`B` (a construction usually written +:math:`\Pi_{x:A}.B` in set theory). + +Non dependent product types have a special notation: :g:`A -> B` stands for +:g:`forall _ : A, B`. The *non dependent product* is used both to denote +the propositional implication and function types. + +Applications +------------ + +The expression :token:`term`\ :math:`_0` :token:`term`\ :math:`_1` denotes the +application of :token:`term`\ :math:`_0` to :token:`term`\ :math:`_1`. + +The expression :token:`term`\ :math:`_0` :token:`term`\ :math:`_1` ... +:token:`term`\ :math:`_n` denotes the application of the term +:token:`term`\ :math:`_0` to the arguments :token:`term`\ :math:`_1` ... then +:token:`term`\ :math:`_n`. It is equivalent to ( … ( :token:`term`\ :math:`_0` +:token:`term`\ :math:`_1` ) … ) :token:`term`\ :math:`_n` : associativity is to the +left. + +The notation :n:`(@ident := @term)` for arguments is used for making +explicit the value of implicit arguments (see +Section :ref:`explicit-applications`). + +.. index:: + single: ... : ... (type cast) + single: ... <: ... + single: ... <<: ... + +Type cast +--------- + +The expression :n:`@term : @type` is a type cast expression. It enforces +the type of :token:`term` to be :token:`type`. + +:n:`@term <: @type` locally sets up the virtual machine for checking that +:token:`term` has type :token:`type`. + +:n:`@term <<: @type` uses native compilation for checking that :token:`term` +has type :token:`type`. + +.. index:: _ + +Inferable subterms +------------------ + +Expressions often contain redundant pieces of information. Subterms that can be +automatically inferred by Coq can be replaced by the symbol ``_`` and Coq will +guess the missing piece of information. + +.. index:: let ... := ... (term) + +.. _let-in: + +Let-in definitions +------------------ + +:n:`let @ident := @term in @term’` +denotes the local binding of :token:`term` to the variable +:token:`ident` in :token:`term`’. There is a syntactic sugar for let-in +definition of functions: :n:`let @ident {+ @binder} := @term in @term’` +stands for :n:`let @ident := fun {+ @binder} => @term in @term’`. + +.. index:: match ... with ... + +Definition by case analysis +--------------------------- + +Objects of inductive types can be destructurated 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. + +This paragraph describes the basic form of pattern matching. See +Section :ref:`Mult-match` and Chapter :ref:`extendedpatternmatching` for the description +of the general form. The basic form of pattern matching is characterized +by a single :token:`match_item` expression, a :token:`mult_pattern` restricted to a +single :token:`pattern` and :token:`pattern` restricted to the form +:n:`@qualid {* @ident}`. + +The expression match ":token:`term`:math:`_0` :token:`return_type` with +:token:`pattern`:math:`_1` => :token:`term`:math:`_1` :math:`|` … :math:`|` +:token:`pattern`:math:`_n` => :token:`term`:math:`_n` end" denotes a +*pattern matching* over the term :token:`term`:math:`_0` (expected to be +of an inductive type :math:`I`). The terms :token:`term`:math:`_1`\ …\ +:token:`term`:math:`_n` are the *branches* of the pattern matching +expression. Each of :token:`pattern`:math:`_i` has a form :token:`qualid` +:token:`ident` where :token:`qualid` must denote a constructor. There should be +exactly one branch for every constructor of :math:`I`. + +The :token:`return_type` expresses 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 :token:`return_type` is the common type of +branches. In this case, :token:`return_type` can usually be omitted as it can be +inferred from the type of the branches [2]_. + +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 “as :token:`ident`” clause where :token:`ident` +is dependent in the return type. For instance, in the following example: + +.. coqtop:: in + + Inductive bool : Type := true : bool | false : bool. + Inductive eq (A:Type) (x:A) : A -> Prop := eq_refl : eq A x x. + Inductive or (A:Prop) (B:Prop) : Prop := + | or_introl : A -> or A B + | or_intror : B -> or A B. + + 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. + +the branches have respective types ":g:`or (eq bool true true) (eq bool true false)`" +and ":g:`or (eq bool false true) (eq bool false false)`" while the whole +pattern matching expression has type ":g:`or (eq bool b true) (eq bool b false)`", +the identifier :g:`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. + + .. coqtop:: none + + Reset bool_case. + + .. coqtop:: in + + 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. + +The second subcase is only relevant for annotated inductive types such +as the equality predicate (see Section :ref:`coq-equality`), +the order predicate on natural numbers or the type of lists of a given +length (see Section :ref:`matching-dependent`). 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 annotations of the inductive type +is expressed using a “:g:`in` :math:`I` :g:`_ … _` :token:`pattern`:math:`_1` … +:token:`pattern`:math:`_n`” clause, where + +- :math:`I` is the inductive type of the term being matched; + +- the :g:`_` are matching the parameters of the inductive type: the + return type is not dependent on them. + +- the :token:`pattern`:math:`_i` are matching the annotations of the + inductive type: the return type is dependent on them + +- in the basic case which we describe below, each :token:`pattern`:math:`_i` + is a name :token:`ident`:math:`_i`; see :ref:`match-in-patterns` for the + general case + +For instance, in the following example: + +.. coqtop:: in + + 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. + +the type of the branch is :g:`eq A x x` because the third argument of +:g:`eq` is :g:`x` in the type of the pattern :g:`eq_refl`. On the contrary, the +type of the whole pattern matching expression has type :g:`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 :g:`eq` is expressed by the identifier :g:`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 annotations. 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 :ref:`if-then-else` and :ref:`irrefutable-patterns`). + +.. index:: + single: fix + single: cofix + +Recursive functions +------------------- + +The expression “``fix`` :token:`ident`:math:`_1` :token:`binder`:math:`_1` ``:`` +:token:`type`:math:`_1` ``:=`` :token:`term`:math:`_1` ``with … with`` +:token:`ident`:math:`_n` :token:`binder`:math:`_n` : :token:`type`:math:`_n` +``:=`` :token:`term`:math:`_n` ``for`` :token:`ident`:math:`_i`” denotes the +:math:`i`-th component of a block of functions defined by mutual structural +recursion. It is the local counterpart of the :cmd:`Fixpoint` command. When +:math:`n=1`, the “``for`` :token:`ident`:math:`_i`” clause is omitted. + +The expression “``cofix`` :token:`ident`:math:`_1` :token:`binder`:math:`_1` ``:`` +:token:`type`:math:`_1` ``with … with`` :token:`ident`:math:`_n` :token:`binder`:math:`_n` +: :token:`type`:math:`_n` ``for`` :token:`ident`:math:`_i`” denotes the +:math:`i`-th component of a block of terms defined by a mutual guarded +co-recursion. It is the local counterpart of the :cmd:`CoFixpoint` command. When +:math:`n=1`, the “``for`` :token:`ident`:math:`_i`” clause is omitted. + +The association of a single fixpoint and a local definition have a special +syntax: :n:`let fix @ident @binders := @term in` stands for +:n:`let @ident := fix @ident @binders := @term in`. The same applies for co-fixpoints. + +.. _vernacular: + +The Vernacular +============== + +.. productionlist:: coq + decorated-sentence : [ `decoration` … `decoration` ] `sentence` + sentence : `assumption` + : `definition` + : `inductive` + : `fixpoint` + : `assertion` `proof` + assumption : `assumption_keyword` `assums`. + assumption_keyword : Axiom | Conjecture + : Parameter | Parameters + : Variable | Variables + : Hypothesis | Hypotheses + assums : `ident` … `ident` : `term` + : ( `ident` … `ident` : `term` ) … ( `ident` … `ident` : `term` ) + definition : [Local] Definition `ident` [`binders`] [: `term`] := `term` . + : Let `ident` [`binders`] [: `term`] := `term` . + inductive : Inductive `ind_body` with … with `ind_body` . + : CoInductive `ind_body` with … with `ind_body` . + ind_body : `ident` [`binders`] : `term` := + : [[|] `ident` [`binders`] [:`term`] | … | `ident` [`binders`] [:`term`]] + fixpoint : Fixpoint `fix_body` with … with `fix_body` . + : CoFixpoint `cofix_body` with … with `cofix_body` . + assertion : `assertion_keyword` `ident` [`binders`] : `term` . + assertion_keyword : Theorem | Lemma + : Remark | Fact + : Corollary | Proposition + : Definition | Example + proof : Proof . … Qed . + : Proof . … Defined . + : Proof . … Admitted . + decoration : #[ `attributes` ] + attributes : [`attribute`, … , `attribute`] + attribute : `ident` + : `ident` = `string` + : `ident` ( `attributes` ) + +.. todo:: This use of … in this grammar is inconsistent + What about removing the proof part of this grammar from this chapter + and putting it somewhere where top-level tactics can be described as well? + See also #7583. + +This grammar describes *The Vernacular* which is the language of +commands of Gallina. A sentence of the vernacular language, like in +many natural languages, begins with a capital letter and ends with a +dot. + +Sentences may be *decorated* with so-called *attributes*, +which are described in the corresponding section (:ref:`gallina-attributes`). + +The different kinds of command are described hereafter. They all suppose +that the terms occurring in the sentences are well-typed. + +.. _gallina-assumptions: + +Assumptions +----------- + +Assumptions extend the environment with axioms, parameters, hypotheses +or variables. An assumption binds an :token:`ident` to a :token:`type`. It is accepted +by Coq if and only if this :token:`type` is a correct type in the environment +preexisting the declaration and if :token:`ident` was not previously defined in +the same module. This :token:`type` is considered to be the type (or +specification, or statement) assumed by :token:`ident` and we say that :token:`ident` +has type :token:`type`. + +.. _Axiom: + +.. cmd:: Parameter @ident : @type + + This command links :token:`type` to the name :token:`ident` as its specification in + the global context. The fact asserted by :token:`type` is thus assumed as a + postulate. + + .. exn:: @ident already exists. + :name: @ident already exists. (Axiom) + :undocumented: + + .. cmdv:: Parameter {+ @ident } : @type + + Adds several parameters with specification :token:`type`. + + .. cmdv:: Parameter {+ ( {+ @ident } : @type ) } + + Adds blocks of parameters with different specifications. + + .. cmdv:: Local Parameter {+ ( {+ @ident } : @type ) } + :name: Local Parameter + + Such parameters are never made accessible through their unqualified name by + :cmd:`Import` and its variants. You have to explicitly give their fully + qualified name to refer to them. + + .. cmdv:: {? Local } Parameters {+ ( {+ @ident } : @type ) } + {? Local } Axiom {+ ( {+ @ident } : @type ) } + {? Local } Axioms {+ ( {+ @ident } : @type ) } + {? Local } Conjecture {+ ( {+ @ident } : @type ) } + {? Local } Conjectures {+ ( {+ @ident } : @type ) } + :name: Parameters; Axiom; Axioms; Conjecture; Conjectures + + These variants are synonyms of :n:`{? Local } Parameter {+ ( {+ @ident } : @type ) }`. + + .. cmdv:: Variable {+ ( {+ @ident } : @type ) } + Variables {+ ( {+ @ident } : @type ) } + Hypothesis {+ ( {+ @ident } : @type ) } + Hypotheses {+ ( {+ @ident } : @type ) } + :name: Variable (outside a section); Variables (outside a section); Hypothesis (outside a section); Hypotheses (outside a section) + + Outside of any section, these variants are synonyms of + :n:`Local Parameter {+ ( {+ @ident } : @type ) }`. + For their meaning inside a section, see :cmd:`Variable` in + :ref:`section-mechanism`. + + .. warn:: @ident is declared as a local axiom [local-declaration,scope] + + Warning generated when using :cmd:`Variable` instead of + :cmd:`Local Parameter`. + +.. note:: + It is advised to use the commands :cmd:`Axiom`, :cmd:`Conjecture` and + :cmd:`Hypothesis` (and their plural forms) for logical postulates (i.e. when + the assertion :token:`type` is of sort :g:`Prop`), and to use the commands + :cmd:`Parameter` and :cmd:`Variable` (and their plural forms) in other cases + (corresponding to the declaration of an abstract mathematical entity). + +.. seealso:: Section :ref:`section-mechanism`. + +.. _gallina-definitions: + +Definitions +----------- + +Definitions extend the environment with associations of names to terms. +A definition can be seen as a way to give a meaning to a name or as a +way to abbreviate a term. In any case, the name can later be replaced at +any time by its definition. + +The operation of unfolding a name into its definition is called +:math:`\delta`-conversion (see Section :ref:`delta-reduction`). A +definition is accepted by the system if and only if the defined term is +well-typed in the current context of the definition and if the name is +not already used. The name defined by the definition is called a +*constant* and the term it refers to is its *body*. A definition has a +type which is the type of its body. + +A formal presentation of constants and environments is given in +Section :ref:`typing-rules`. + +.. cmd:: Definition @ident := @term + + This command binds :token:`term` to the name :token:`ident` in the environment, + provided that :token:`term` is well-typed. + + .. exn:: @ident already exists. + :name: @ident already exists. (Definition) + :undocumented: + + .. cmdv:: Definition @ident : @type := @term + + This variant checks that the type of :token:`term` is definitionally equal to + :token:`type`, and registers :token:`ident` as being of type + :token:`type`, and bound to value :token:`term`. + + .. exn:: The term @term has type @type while it is expected to have type @type'. + :undocumented: + + .. cmdv:: Definition @ident @binders {? : @type } := @term + + This is equivalent to + :n:`Definition @ident : forall @binders, @type := fun @binders => @term`. + + .. cmdv:: Local Definition @ident {? @binders } {? : @type } := @term + :name: Local Definition + + Such definitions are never made accessible through their + unqualified name by :cmd:`Import` and its variants. + You have to explicitly give their fully qualified name to refer to them. + + .. cmdv:: {? Local } Example @ident {? @binders } {? : @type } := @term + :name: Example + + This is equivalent to :cmd:`Definition`. + + .. cmdv:: Let @ident := @term + :name: Let (outside a section) + + Outside of any section, this variant is a synonym of + :n:`Local Definition @ident := @term`. + For its meaning inside a section, see :cmd:`Let` in + :ref:`section-mechanism`. + + .. warn:: @ident is declared as a local definition [local-declaration,scope] + + Warning generated when using :cmd:`Let` instead of + :cmd:`Local Definition`. + +.. seealso:: Section :ref:`section-mechanism`, commands :cmd:`Opaque`, + :cmd:`Transparent`, and tactic :tacn:`unfold`. + +.. _gallina-inductive-definitions: + +Inductive definitions +--------------------- + +We gradually explain simple inductive types, simple annotated inductive +types, simple parametric inductive types, mutually inductive types. We +explain also co-inductive types. + +Simple inductive types +~~~~~~~~~~~~~~~~~~~~~~ + +.. cmd:: Inductive @ident : {? @sort } := {? | } @ident : @type {* | @ident : @type } + + This command defines a simple inductive type and its constructors. + The first :token:`ident` is the name of the inductively defined type + and :token:`sort` is the universe where it lives. The next :token:`ident`\s + are the names of its constructors and :token:`type` their respective types. + Depending on the universe where the inductive type :token:`ident` lives + (e.g. its type :token:`sort`), Coq provides a number of destructors. + Destructors are named :token:`ident`\ ``_sind``,:token:`ident`\ ``_ind``, + :token:`ident`\ ``_rec`` or :token:`ident`\ ``_rect`` which respectively + correspond to elimination principles on :g:`SProp`, :g:`Prop`, :g:`Set` and :g:`Type`. + The type of the destructors expresses structural induction/recursion + principles over objects of type :token:`ident`. + The constant :token:`ident`\ ``_ind`` is always provided, + whereas :token:`ident`\ ``_rec`` and :token:`ident`\ ``_rect`` can be + impossible to derive (for example, when :token:`ident` is a proposition). + + .. exn:: Non strictly positive occurrence of @ident in @type. + + The types of the constructors have to satisfy a *positivity condition* + (see Section :ref:`positivity`). This condition ensures the soundness of + the inductive definition. + + .. exn:: The conclusion of @type is not valid; it must be built from @ident. + + The conclusion of the type of the constructors must be the inductive type + :token:`ident` being defined (or :token:`ident` applied to arguments in + the case of annotated inductive types — cf. next section). + + .. example:: + + The set of natural numbers is defined as: + + .. coqtop:: all + + Inductive nat : Set := + | O : nat + | S : nat -> nat. + + The type nat is defined as the least :g:`Set` containing :g:`O` and closed by + the :g:`S` constructor. The names :g:`nat`, :g:`O` and :g:`S` are added to the + environment. + + Now let us have a look at the elimination principles. They are three of them: + :g:`nat_ind`, :g:`nat_rec` and :g:`nat_rect`. The type of :g:`nat_ind` is: + + .. coqtop:: all + + Check nat_ind. + + This is the well known structural induction principle over natural + numbers, i.e. the second-order form of Peano’s induction principle. It + allows proving some universal property of natural numbers (:g:`forall + n:nat, P n`) by induction on :g:`n`. + + The types of :g:`nat_rec` and :g:`nat_rect` are similar, except that they pertain + to :g:`(P:nat->Set)` and :g:`(P:nat->Type)` respectively. They correspond to + primitive induction principles (allowing dependent types) respectively + over sorts ``Set`` and ``Type``. + + .. cmdv:: Inductive @ident {? : @sort } := {? | } {*| @ident {? @binders } {? : @type } } + + Constructors :token:`ident`\s can come with :token:`binders` in which case, + the actual type of the constructor is :n:`forall @binders, @type`. + + In the case where inductive types have no annotations (next section + gives an example of such annotations), a constructor can be defined + by only giving the type of its arguments. + + .. example:: + + .. coqtop:: none + + Reset nat. + + .. coqtop:: in + + Inductive nat : Set := O | S (_:nat). + + +Simple annotated inductive types +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +In an annotated inductive types, the universe where the inductive type +is defined is no longer a simple sort, but what is called an arity, +which is a type whose conclusion is a sort. + +.. example:: + + As an example of annotated inductive types, let us define the + :g:`even` predicate: + + .. coqtop:: all + + Inductive even : nat -> Prop := + | even_0 : even O + | even_SS : forall n:nat, even n -> even (S (S n)). + + The type :g:`nat->Prop` means that even is a unary predicate (inductively + defined) over natural numbers. The type of its two constructors are the + defining clauses of the predicate even. The type of :g:`even_ind` is: + + .. coqtop:: all + + Check even_ind. + + From a mathematical point of view it asserts that the natural numbers satisfying + the predicate even are exactly in the smallest set of naturals satisfying the + clauses :g:`even_0` or :g:`even_SS`. This is why, when we want to prove any + predicate :g:`P` over elements of :g:`even`, it is enough to prove it for :g:`O` + and to prove that if any natural number :g:`n` satisfies :g:`P` its double + successor :g:`(S (S n))` satisfies also :g:`P`. This is indeed analogous to the + structural induction principle we got for :g:`nat`. + +Parameterized inductive types +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. cmdv:: Inductive @ident @binders {? : @type } := {? | } @ident : @type {* | @ident : @type} + + In the previous example, each constructor introduces a different + instance of the predicate :g:`even`. In some cases, all the constructors + introduce the same generic instance of the inductive definition, in + which case, instead of an annotation, we use a context of parameters + which are :token:`binders` shared by all the constructors of the definition. + + Parameters differ from inductive type annotations in the fact that the + conclusion of each type of constructor invoke the inductive type with + the same values of parameters as its specification. + + .. example:: + + A typical example is the definition of polymorphic lists: + + .. coqtop:: in + + Inductive list (A:Set) : Set := + | nil : list A + | cons : A -> list A -> list A. + + In the type of :g:`nil` and :g:`cons`, we write :g:`(list A)` and not + just :g:`list`. The constructors :g:`nil` and :g:`cons` will have respectively + types: + + .. coqtop:: all + + Check nil. + Check cons. + + Types of destructors are also quantified with :g:`(A:Set)`. + + Once again, it is possible to specify only the type of the arguments + of the constructors, and to omit the type of the conclusion: + + .. coqtop:: none + + Reset list. + + .. coqtop:: in + + Inductive list (A:Set) : Set := nil | cons (_:A) (_:list A). + +.. note:: + + It is possible in the type of a constructor, to + invoke recursively the inductive definition on an argument which is not + the parameter itself. + + One can define : + + .. coqtop:: all + + Inductive list2 (A:Set) : Set := + | nil2 : list2 A + | cons2 : A -> list2 (A*A) -> list2 A. + + that can also be written by specifying only the type of the arguments: + + .. coqtop:: all reset + + Inductive list2 (A:Set) : Set := nil2 | cons2 (_:A) (_:list2 (A*A)). + + But the following definition will give an error: + + .. coqtop:: all + + Fail Inductive listw (A:Set) : Set := + | nilw : listw (A*A) + | consw : A -> listw (A*A) -> listw (A*A). + + because the conclusion of the type of constructors should be :g:`listw A` + in both cases. + + + A parameterized inductive definition can be defined using annotations + instead of parameters but it will sometimes give a different (bigger) + sort for the inductive definition and will produce a less convenient + rule for case elimination. + +.. flag:: Uniform Inductive Parameters + + When this option is set (it is off by default), + inductive definitions are abstracted over their parameters + before type checking constructors, allowing to write: + + .. coqtop:: all + + Set Uniform Inductive Parameters. + Inductive list3 (A:Set) : Set := + | nil3 : list3 + | cons3 : A -> list3 -> list3. + + This behavior is essentially equivalent to starting a new section + and using :cmd:`Context` to give the uniform parameters, like so + (cf. :ref:`section-mechanism`): + + .. coqtop:: all reset + + Section list3. + Context (A:Set). + Inductive list3 : Set := + | nil3 : list3 + | cons3 : A -> list3 -> list3. + End list3. + +.. seealso:: + Section :ref:`inductive-definitions` and the :tacn:`induction` tactic. + +Variants +~~~~~~~~ + +.. cmd:: Variant @ident @binders {? : @type } := {? | } @ident : @type {* | @ident : @type} + + The :cmd:`Variant` command is identical to the :cmd:`Inductive` command, except + that it disallows recursive definition of types (for instance, lists cannot + be defined using :cmd:`Variant`). No induction scheme is generated for + this variant, unless option :flag:`Nonrecursive Elimination Schemes` is on. + + .. exn:: The @num th argument of @ident must be @ident in @type. + :undocumented: + +Mutually defined inductive types +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. cmdv:: Inductive @ident {? : @type } := {? | } {*| @ident : @type } {* with {? | } {*| @ident {? : @type } } } + + This variant allows defining a block of mutually inductive types. + It has the same semantics as the above :cmd:`Inductive` definition for each + :token:`ident`. All :token:`ident` are simultaneously added to the environment. + Then well-typing of constructors can be checked. Each one of the :token:`ident` + can be used on its own. + + .. cmdv:: Inductive @ident @binders {? : @type } := {? | } {*| @ident : @type } {* with {? | } {*| @ident @binders {? : @type } } } + + In this variant, the inductive definitions are parameterized + with :token:`binders`. However, parameters correspond to a local context + in which the whole set of inductive declarations is done. For this + reason, the parameters must be strictly the same for each inductive types. + +.. example:: + + The typical example of a mutual inductive data type is the one for trees and + forests. We assume given two types :g:`A` and :g:`B` as variables. It can + be declared the following way. + + .. coqtop:: in + + Parameters A B : Set. + + Inductive tree : Set := node : A -> forest -> tree + + with forest : Set := + | leaf : B -> forest + | cons : tree -> forest -> forest. + + This declaration generates automatically six induction principles. They are + respectively called :g:`tree_rec`, :g:`tree_ind`, :g:`tree_rect`, + :g:`forest_rec`, :g:`forest_ind`, :g:`forest_rect`. These ones are not the most + general ones but are just the induction principles corresponding to each + inductive part seen as a single inductive definition. + + To illustrate this point on our example, we give the types of :g:`tree_rec` + and :g:`forest_rec`. + + .. coqtop:: all + + Check tree_rec. + + Check forest_rec. + + Assume we want to parameterize our mutual inductive definitions with the + two type variables :g:`A` and :g:`B`, the declaration should be + done the following way: + + .. coqdoc:: + + Inductive tree (A B:Set) : Set := node : A -> forest A B -> tree A B + + with forest (A B:Set) : Set := + | leaf : B -> forest A B + | cons : tree A B -> forest A B -> forest A B. + + Assume we define an inductive definition inside a section + (cf. :ref:`section-mechanism`). When the section is closed, the variables + declared in the section and occurring free in the declaration are added as + parameters to the inductive definition. + +.. seealso:: + A generic command :cmd:`Scheme` is useful to build automatically various + mutual induction principles. + +.. _coinductive-types: + +Co-inductive types +~~~~~~~~~~~~~~~~~~ + +The objects of an inductive type are well-founded with respect to the +constructors of the type. In other words, such objects contain only a +*finite* number of constructors. Co-inductive types arise from relaxing +this condition, and admitting types whose objects contain an infinity of +constructors. Infinite objects are introduced by a non-ending (but +effective) process of construction, defined in terms of the constructors +of the type. + +.. cmd:: CoInductive @ident @binders {? : @type } := {? | } @ident : @type {* | @ident : @type} + + This command introduces a co-inductive type. + The syntax of the command is the same as the command :cmd:`Inductive`. + No principle of induction is derived from the definition of a co-inductive + type, since such principles only make sense for inductive types. + For co-inductive types, the only elimination principle is case analysis. + +.. example:: + + An example of a co-inductive type is the type of infinite sequences of + natural numbers, usually called streams. + + .. coqtop:: in + + CoInductive Stream : Set := Seq : nat -> Stream -> Stream. + + The usual destructors on streams :g:`hd:Stream->nat` and :g:`tl:Str->Str` + can be defined as follows: + + .. coqtop:: in + + Definition hd (x:Stream) := let (a,s) := x in a. + Definition tl (x:Stream) := let (a,s) := x in s. + +Definition of co-inductive predicates and blocks of mutually +co-inductive definitions are also allowed. + +.. example:: + + An example of a co-inductive predicate is the extensional equality on + streams: + + .. coqtop:: in + + CoInductive EqSt : Stream -> Stream -> Prop := + eqst : forall s1 s2:Stream, + hd s1 = hd s2 -> EqSt (tl s1) (tl s2) -> EqSt s1 s2. + + In order to prove the extensional equality of two streams :g:`s1` and :g:`s2` + we have to construct an infinite proof of equality, that is, an infinite + object of type :g:`(EqSt s1 s2)`. We will see how to introduce infinite + objects in Section :ref:`cofixpoint`. + +Caveat +++++++ + +The ability to define co-inductive types by constructors, hereafter called +*positive co-inductive types*, is known to break subject reduction. The story is +a bit long: this is due to dependent pattern-matching which implies +propositional η-equality, which itself would require full η-conversion for +subject reduction to hold, but full η-conversion is not acceptable as it would +make type-checking undecidable. + +Since the introduction of primitive records in Coq 8.5, an alternative +presentation is available, called *negative co-inductive types*. This consists +in defining a co-inductive type as a primitive record type through its +projections. Such a technique is akin to the *co-pattern* style that can be +found in e.g. Agda, and preserves subject reduction. + +The above example can be rewritten in the following way. + +.. coqtop:: none + + Reset Stream. + +.. coqtop:: all + + Set Primitive Projections. + CoInductive Stream : Set := Seq { hd : nat; tl : Stream }. + CoInductive EqSt (s1 s2: Stream) : Prop := eqst { + eqst_hd : hd s1 = hd s2; + eqst_tl : EqSt (tl s1) (tl s2); + }. + +Some properties that hold over positive streams are lost when going to the +negative presentation, typically when they imply equality over streams. +For instance, propositional η-equality is lost when going to the negative +presentation. It is nonetheless logically consistent to recover it through an +axiom. + +.. coqtop:: all + + Axiom Stream_eta : forall s: Stream, s = Seq (hd s) (tl s). + +More generally, as in the case of positive coinductive types, it is consistent +to further identify extensional equality of coinductive types with propositional +equality: + +.. coqtop:: all + + Axiom Stream_ext : forall (s1 s2: Stream), EqSt s1 s2 -> s1 = s2. + +As of Coq 8.9, it is now advised to use negative co-inductive types rather than +their positive counterparts. + +.. seealso:: + :ref:`primitive_projections` for more information about negative + records and primitive projections. + + +Definition of recursive functions +--------------------------------- + +Definition of functions by recursion over inductive objects +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +This section describes the primitive form of definition by recursion over +inductive objects. See the :cmd:`Function` command for more advanced +constructions. + +.. _Fixpoint: + +.. cmd:: Fixpoint @ident @binders {? {struct @ident} } {? : @type } := @term + + This command allows defining functions by pattern matching over inductive + objects using a fixed point construction. The meaning of this declaration is + to define :token:`ident` a recursive function with arguments specified by + the :token:`binders` such that :token:`ident` applied to arguments + corresponding to these :token:`binders` has type :token:`type`, and is + equivalent to the expression :token:`term`. The type of :token:`ident` is + consequently :n:`forall @binders, @type` and its value is equivalent + to :n:`fun @binders => @term`. + + To be accepted, a :cmd:`Fixpoint` definition has to satisfy some syntactical + constraints on a special argument called the decreasing argument. They + are needed to ensure that the :cmd:`Fixpoint` definition always terminates. + The point of the :n:`{struct @ident}` annotation is to let the user tell the + system which argument decreases along the recursive calls. + + The :n:`{struct @ident}` annotation may be left implicit, in this case the + system tries successively arguments from left to right until it finds one + that satisfies the decreasing condition. + + .. note:: + + + Some fixpoints may have several arguments that fit as decreasing + arguments, and this choice influences the reduction of the fixpoint. + Hence an explicit annotation must be used if the leftmost decreasing + argument is not the desired one. Writing explicit annotations can also + speed up type checking of large mutual fixpoints. + + + In order to keep the strong normalization property, the fixed point + reduction will only be performed when the argument in position of the + decreasing argument (which type should be in an inductive definition) + starts with a constructor. + + + .. example:: + + One can define the addition function as : + + .. coqtop:: all + + Fixpoint add (n m:nat) {struct n} : nat := + match n with + | O => m + | S p => S (add p m) + end. + + The match operator matches a value (here :g:`n`) with the various + constructors of its (inductive) type. The remaining arguments give the + respective values to be returned, as functions of the parameters of the + corresponding constructor. Thus here when :g:`n` equals :g:`O` we return + :g:`m`, and when :g:`n` equals :g:`(S p)` we return :g:`(S (add p m))`. + + The match operator is formally described in + Section :ref:`match-construction`. + The system recognizes that in the inductive call :g:`(add p m)` the first + argument actually decreases because it is a *pattern variable* coming + from :g:`match n with`. + + .. example:: + + The following definition is not correct and generates an error message: + + .. coqtop:: all + + Fail Fixpoint wrongplus (n m:nat) {struct n} : nat := + match m with + | O => n + | S p => S (wrongplus n p) + end. + + because the declared decreasing argument :g:`n` does not actually + decrease in the recursive call. The function computing the addition over + the second argument should rather be written: + + .. coqtop:: all + + Fixpoint plus (n m:nat) {struct m} : nat := + match m with + | O => n + | S p => S (plus n p) + end. + + .. example:: + + The recursive call may not only be on direct subterms of the recursive + variable :g:`n` but also on a deeper subterm and we can directly write + the function :g:`mod2` which gives the remainder modulo 2 of a natural + number. + + .. coqtop:: all + + Fixpoint mod2 (n:nat) : nat := + match n with + | O => O + | S p => match p with + | O => S O + | S q => mod2 q + end + end. + + + .. cmdv:: Fixpoint @ident @binders {? {struct @ident} } {? : @type } := @term {* with @ident @binders {? : @type } := @term } + + This variant allows defining simultaneously several mutual fixpoints. + It is especially useful when defining functions over mutually defined + inductive types. + + .. example:: + + The size of trees and forests can be defined the following way: + + .. coqtop:: all + + Fixpoint tree_size (t:tree) : nat := + match t with + | node a f => S (forest_size f) + end + with forest_size (f:forest) : nat := + match f with + | leaf b => 1 + | cons t f' => (tree_size t + forest_size f') + end. + +.. _cofixpoint: + +Definitions of recursive objects in co-inductive types +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. cmd:: CoFixpoint @ident {? @binders } {? : @type } := @term + + This command introduces a method for constructing an infinite object of a + coinductive type. For example, the stream containing all natural numbers can + be introduced applying the following method to the number :g:`O` (see + Section :ref:`coinductive-types` for the definition of :g:`Stream`, :g:`hd` + and :g:`tl`): + + .. coqtop:: all + + CoFixpoint from (n:nat) : Stream := Seq n (from (S n)). + + Oppositely to recursive ones, there is no decreasing argument in a + co-recursive definition. To be admissible, a method of construction must + provide at least one extra constructor of the infinite object for each + iteration. A syntactical guard condition is imposed on co-recursive + definitions in order to ensure this: each recursive call in the + definition must be protected by at least one constructor, and only by + constructors. That is the case in the former definition, where the single + recursive call of :g:`from` is guarded by an application of :g:`Seq`. + On the contrary, the following recursive function does not satisfy the + guard condition: + + .. coqtop:: all + + Fail CoFixpoint filter (p:nat -> bool) (s:Stream) : Stream := + if p (hd s) then Seq (hd s) (filter p (tl s)) else filter p (tl s). + + The elimination of co-recursive definition is done lazily, i.e. the + definition is expanded only when it occurs at the head of an application + which is the argument of a case analysis expression. In any other + context, it is considered as a canonical expression which is completely + evaluated. We can test this using the command :cmd:`Eval`, which computes + the normal forms of a term: + + .. coqtop:: all + + Eval compute in (from 0). + Eval compute in (hd (from 0)). + Eval compute in (tl (from 0)). + + .. cmdv:: CoFixpoint @ident {? @binders } {? : @type } := @term {* with @ident {? @binders } : {? @type } := @term } + + As in the :cmd:`Fixpoint` command, it is possible to introduce a block of + mutually dependent methods. + +.. _Assertions: + +Assertions and proofs +--------------------- + +An assertion states a proposition (or a type) of which the proof (or an +inhabitant of the type) is interactively built using tactics. The interactive +proof mode is described in Chapter :ref:`proofhandling` and the tactics in +Chapter :ref:`Tactics`. The basic assertion command is: + +.. cmd:: Theorem @ident {? @binders } : @type + + After the statement is asserted, Coq needs a proof. Once a proof of + :token:`type` under the assumptions represented by :token:`binders` is given and + validated, the proof is generalized into a proof of :n:`forall @binders, @type` and + the theorem is bound to the name :token:`ident` in the environment. + + .. exn:: The term @term has type @type which should be Set, Prop or Type. + :undocumented: + + .. exn:: @ident already exists. + :name: @ident already exists. (Theorem) + + The name you provided is already defined. You have then to choose + another name. + + .. exn:: Nested proofs are not allowed unless you turn option Nested Proofs Allowed on. + + You are asserting a new statement while already being in proof editing mode. + This feature, called nested proofs, is disabled by default. + To activate it, turn option :flag:`Nested Proofs Allowed` on. + + .. cmdv:: Lemma @ident {? @binders } : @type + Remark @ident {? @binders } : @type + Fact @ident {? @binders } : @type + Corollary @ident {? @binders } : @type + Proposition @ident {? @binders } : @type + :name: Lemma; Remark; Fact; Corollary; Proposition + + These commands are all synonyms of :n:`Theorem @ident {? @binders } : type`. + +.. cmdv:: Theorem @ident {? @binders } : @type {* with @ident {? @binders } : @type} + + This command is useful for theorems that are proved by simultaneous induction + over a mutually inductive assumption, or that assert mutually dependent + statements in some mutual co-inductive type. It is equivalent to + :cmd:`Fixpoint` or :cmd:`CoFixpoint` but using tactics to build the proof of + the statements (or the body of the specification, depending on the point of + view). The inductive or co-inductive types on which the induction or + coinduction has to be done is assumed to be non ambiguous and is guessed by + the system. + + Like in a :cmd:`Fixpoint` or :cmd:`CoFixpoint` definition, the induction hypotheses + have to be used on *structurally smaller* arguments (for a :cmd:`Fixpoint`) or + be *guarded by a constructor* (for a :cmd:`CoFixpoint`). The verification that + recursive proof arguments are correct is done only at the time of registering + the lemma in the environment. To know if the use of induction hypotheses is + correct at some time of the interactive development of a proof, use the + command :cmd:`Guarded`. + + The command can be used also with :cmd:`Lemma`, :cmd:`Remark`, etc. instead of + :cmd:`Theorem`. + +.. cmdv:: Definition @ident {? @binders } : @type + + This allows defining a term of type :token:`type` using the proof editing + mode. It behaves as :cmd:`Theorem` but is intended to be used in conjunction with + :cmd:`Defined` in order to define a constant of which the computational + behavior is relevant. + + The command can be used also with :cmd:`Example` instead of :cmd:`Definition`. + + .. seealso:: :cmd:`Opaque`, :cmd:`Transparent`, :tacn:`unfold`. + +.. cmdv:: Let @ident {? @binders } : @type + + Like :n:`Definition @ident {? @binders } : @type` except that the definition is + turned into a let-in definition generalized over the declarations depending + on it after closing the current section. + +.. cmdv:: Fixpoint @ident @binders : @type {* with @ident @binders : @type} + + This generalizes the syntax of :cmd:`Fixpoint` so that one or more bodies + can be defined interactively using the proof editing mode (when a + body is omitted, its type is mandatory in the syntax). When the block + of proofs is completed, it is intended to be ended by :cmd:`Defined`. + +.. cmdv:: CoFixpoint @ident {? @binders } : @type {* with @ident {? @binders } : @type} + + This generalizes the syntax of :cmd:`CoFixpoint` so that one or more bodies + can be defined interactively using the proof editing mode. + +A proof starts by the keyword :cmd:`Proof`. Then Coq enters the proof editing mode +until the proof is completed. The proof editing mode essentially contains +tactics that are described in chapter :ref:`Tactics`. Besides tactics, there +are commands to manage the proof editing mode. They are described in Chapter +:ref:`proofhandling`. + +When the proof is completed it should be validated and put in the environment +using the keyword :cmd:`Qed`. + +.. note:: + + #. Several statements can be simultaneously asserted provided option + :flag:`Nested Proofs Allowed` was turned on. + + #. Not only other assertions but any vernacular command can be given + while in the process of proving a given assertion. In this case, the + command is understood as if it would have been given before the + statements still to be proved. Nonetheless, this practice is discouraged + and may stop working in future versions. + + #. Proofs ended by :cmd:`Qed` are declared opaque. Their content cannot be + unfolded (see :ref:`performingcomputations`), thus + realizing some form of *proof-irrelevance*. To be able to unfold a + proof, the proof should be ended by :cmd:`Defined`. + + #. :cmd:`Proof` is recommended but can currently be omitted. On the opposite + side, :cmd:`Qed` (or :cmd:`Defined`) is mandatory to validate a proof. + + #. One can also use :cmd:`Admitted` in place of :cmd:`Qed` to turn the + current asserted statement into an axiom and exit the proof editing mode. + +.. _gallina-attributes: + +Attributes +----------- + +Any vernacular command can be decorated with a list of attributes, enclosed +between ``#[`` (hash and opening square bracket) and ``]`` (closing square bracket) +and separated by commas ``,``. Multiple space-separated blocks may be provided. + +Each attribute has a name (an identifier) and may have a value. +A value is either a :token:`string` (in which case it is specified with an equal ``=`` sign), +or a list of attributes, enclosed within brackets. + +Currently, +the following attributes names are recognized: + +``monomorphic``, ``polymorphic`` + Take no value, analogous to the ``Monomorphic`` and ``Polymorphic`` flags + (see :ref:`polymorphicuniverses`). + +``program`` + Takes no value, analogous to the ``Program`` flag + (see :ref:`programs`). + +``global``, ``local`` + Take no value, analogous to the ``Global`` and ``Local`` flags + (see :ref:`controlling-locality-of-commands`). + +``deprecated`` + Takes as value the optional attributes ``since`` and ``note``; + both have a string value. + + This attribute can trigger the following warnings: + + .. warn:: Tactic @qualid is deprecated since @string. @string. + :undocumented: + + .. warn:: Tactic Notation @qualid is deprecated since @string. @string. + :undocumented: + +.. example:: + + .. coqtop:: all reset warn + + From Coq Require Program. + #[program] Definition one : nat := S _. + Next Obligation. + exact O. + Defined. + + #[deprecated(since="8.9.0", note="Use idtac instead.")] + Ltac foo := idtac. + + Goal True. + Proof. + now foo. + Abort. + +.. [1] + This is similar to the expression “*entry* :math:`\{` sep *entry* + :math:`\}`” in standard BNF, or “*entry* :math:`(` sep *entry* + :math:`)`\ \*” in the syntax of regular expressions. + +.. [2] + Except if the inductive type is empty in which case there is no + equation that can be used to infer the return type. diff --git a/doc/sphinx/language/module-system.rst b/doc/sphinx/language/module-system.rst new file mode 100644 index 0000000000..15fee91245 --- /dev/null +++ b/doc/sphinx/language/module-system.rst @@ -0,0 +1,456 @@ +.. _themodulesystem: + +The Module System +================= + +The module system extends the Calculus of Inductive Constructions +providing a convenient way to structure large developments as well as +a means of massive abstraction. + + +Modules and module types +---------------------------- + +**Access path.** An access path is denoted by :math:`p` and can be +either a module variable :math:`X` or, if :math:`p′` is an access path +and :math:`id` an identifier, then :math:`p′.id` is an access path. + + +**Structure element.** A structure element is denoted by :math:`e` and +is either a definition of a constant, an assumption, a definition of +an inductive, a definition of a module, an alias of a module or a module +type abbreviation. + + +**Structure expression.** A structure expression is denoted by :math:`S` and can be: + ++ an access path :math:`p` ++ a plain structure :math:`\Struct~e ; … ; e~\End` ++ a functor :math:`\Functor(X:S)~S′`, where :math:`X` is a module variable, :math:`S` and :math:`S′` are + structure expressions ++ an application :math:`S~p`, where :math:`S` is a structure expression and :math:`p` an + access path ++ a refined structure :math:`S~\with~p := p`′ or :math:`S~\with~p := t:T` where :math:`S` is a + structure expression, :math:`p` and :math:`p′` are access paths, :math:`t` is a term and :math:`T` is + the type of :math:`t`. + +**Module definition.** A module definition is written :math:`\Mod{X}{S}{S'}` +and consists of a module variable :math:`X`, a module type +:math:`S` which can be any structure expression and optionally a +module implementation :math:`S′` which can be any structure expression +except a refined structure. + + +**Module alias.** A module alias is written :math:`\ModA{X}{p}` +and consists of a module variable :math:`X` and a module path +:math:`p`. + +**Module type abbreviation.** +A module type abbreviation is written :math:`\ModType{Y}{S}`, +where :math:`Y` is an identifier and :math:`S` is any structure +expression . + + +Typing Modules +------------------ + +In order to introduce the typing system we first slightly extend the syntactic +class of terms and environments given in section :ref:`The-terms`. The +environments, apart from definitions of constants and inductive types now also +hold any other structure elements. Terms, apart from variables, constants and +complex terms, include also access paths. + +We also need additional typing judgments: + + ++ :math:`\WFT{E}{S}`, denoting that a structure :math:`S` is well-formed, ++ :math:`\WTM{E}{p}{S}`, denoting that the module pointed by :math:`p` has type :math:`S` in + environment :math:`E`. ++ :math:`\WEV{E}{S}{\ovl{S}}`, denoting that a structure :math:`S` is evaluated to a + structure :math:`S` in weak head normal form. ++ :math:`\WS{E}{S_1}{S_2}` , denoting that a structure :math:`S_1` is a subtype of a + structure :math:`S_2`. ++ :math:`\WS{E}{e_1}{e_2}` , denoting that a structure element e_1 is more + precise than a structure element e_2. + +The rules for forming structures are the following: + +.. inference:: WF-STR + + \WF{E;E′}{} + ------------------------ + \WFT{E}{ \Struct~E′ ~\End} + +.. inference:: WF-FUN + + \WFT{E; \ModS{X}{S}}{ \ovl{S′} } + -------------------------- + \WFT{E}{ \Functor(X:S)~S′} + + +Evaluation of structures to weak head normal form: + +.. inference:: WEVAL-APP + + \begin{array}{c} + \WEV{E}{S}{\Functor(X:S_1 )~S_2}~~~~~\WEV{E}{S_1}{\ovl{S_1}} \\ + \WTM{E}{p}{S_3}~~~~~ \WS{E}{S_3}{\ovl{S_1}} + \end{array} + -------------------------- + \WEV{E}{S~p}{S_2 \{p/X,t_1 /p_1 .c_1 ,…,t_n /p_n.c_n \}} + + +In the last rule, :math:`\{t_1 /p_1 .c_1 ,…,t_n /p_n .c_n \}` is the resulting +substitution from the inlining mechanism. We substitute in :math:`S` the +inlined fields :math:`p_i .c_i` from :math:`\ModS{X}{S_1 }` by the corresponding delta- +reduced term :math:`t_i` in :math:`p`. + +.. inference:: WEVAL-WITH-MOD + + \begin{array}{c} + E[] ⊢ S \lra \Struct~e_1 ;…;e_i ; \ModS{X}{S_1 };e_{i+2} ;… ;e_n ~\End \\ + E;e_1 ;…;e_i [] ⊢ S_1 \lra \ovl{S_1} ~~~~~~ + E[] ⊢ p : S_2 \\ + E;e_1 ;…;e_i [] ⊢ S_2 <: \ovl{S_1} + \end{array} + ---------------------------------- + \begin{array}{c} + \WEV{E}{S~\with~x := p}{}\\ + \Struct~e_1 ;…;e_i ; \ModA{X}{p};e_{i+2} \{p/X\} ;…;e_n \{p/X\} ~\End + \end{array} + +.. inference:: WEVAL-WITH-MOD-REC + + \begin{array}{c} + \WEV{E}{S}{\Struct~e_1 ;…;e_i ; \ModS{X_1}{S_1 };e_{i+2} ;… ;e_n ~\End} \\ + \WEV{E;e_1 ;…;e_i }{S_1~\with~p := p_1}{\ovl{S_2}} + \end{array} + -------------------------- + \begin{array}{c} + \WEV{E}{S~\with~X_1.p := p_1}{} \\ + \Struct~e_1 ;…;e_i ; \ModS{X}{\ovl{S_2}};e_{i+2} \{p_1 /X_1.p\} ;…;e_n \{p_1 /X_1.p\} ~\End + \end{array} + +.. inference:: WEVAL-WITH-DEF + + \begin{array}{c} + \WEV{E}{S}{\Struct~e_1 ;…;e_i ;\Assum{}{c}{T_1};e_{i+2} ;… ;e_n ~\End} \\ + \WS{E;e_1 ;…;e_i }{Def()(c:=t:T)}{\Assum{}{c}{T_1}} + \end{array} + -------------------------- + \begin{array}{c} + \WEV{E}{S~\with~c := t:T}{} \\ + \Struct~e_1 ;…;e_i ;Def()(c:=t:T);e_{i+2} ;… ;e_n ~\End + \end{array} + +.. inference:: WEVAL-WITH-DEF-REC + + \begin{array}{c} + \WEV{E}{S}{\Struct~e_1 ;…;e_i ; \ModS{X_1 }{S_1 };e_{i+2} ;… ;e_n ~\End} \\ + \WEV{E;e_1 ;…;e_i }{S_1~\with~p := p_1}{\ovl{S_2}} + \end{array} + -------------------------- + \begin{array}{c} + \WEV{E}{S~\with~X_1.p := t:T}{} \\ + \Struct~e_1 ;…;e_i ; \ModS{X}{\ovl{S_2} };e_{i+2} ;… ;e_n ~\End + \end{array} + +.. inference:: WEVAL-PATH-MOD1 + + \begin{array}{c} + \WEV{E}{p}{\Struct~e_1 ;…;e_i ; \Mod{X}{S}{S_1};e_{i+2} ;… ;e_n End} \\ + \WEV{E;e_1 ;…;e_i }{S}{\ovl{S}} + \end{array} + -------------------------- + E[] ⊢ p.X \lra \ovl{S} + +.. inference:: WEVAL-PATH-MOD2 + + \WF{E}{} + \Mod{X}{S}{S_1}∈ E + \WEV{E}{S}{\ovl{S}} + -------------------------- + \WEV{E}{X}{\ovl{S}} + +.. inference:: WEVAL-PATH-ALIAS1 + + \begin{array}{c} + \WEV{E}{p}{~\Struct~e_1 ;…;e_i ; \ModA{X}{p_1};e_{i+2} ;… ;e_n End} \\ + \WEV{E;e_1 ;…;e_i }{p_1}{\ovl{S}} + \end{array} + -------------------------- + \WEV{E}{p.X}{\ovl{S}} + +.. inference:: WEVAL-PATH-ALIAS2 + + \WF{E}{} + \ModA{X}{p_1 }∈ E + \WEV{E}{p_1}{\ovl{S}} + -------------------------- + \WEV{E}{X}{\ovl{S}} + +.. inference:: WEVAL-PATH-TYPE1 + + \begin{array}{c} + \WEV{E}{p}{~\Struct~e_1 ;…;e_i ; \ModType{Y}{S};e_{i+2} ;… ;e_n End} \\ + \WEV{E;e_1 ;…;e_i }{S}{\ovl{S}} + \end{array} + -------------------------- + \WEV{E}{p.Y}{\ovl{S}} + +.. inference:: WEVAL-PATH-TYPE2 + + \WF{E}{} + \ModType{Y}{S}∈ E + \WEV{E}{S}{\ovl{S}} + -------------------------- + \WEV{E}{Y}{\ovl{S}} + + +Rules for typing module: + +.. inference:: MT-EVAL + + \WEV{E}{p}{\ovl{S}} + -------------------------- + E[] ⊢ p : \ovl{S} + +.. inference:: MT-STR + + E[] ⊢ p : S + -------------------------- + E[] ⊢ p : S/p + + +The last rule, called strengthening is used to make all module fields +manifestly equal to themselves. The notation :math:`S/p` has the following +meaning: + + ++ if :math:`S\lra~\Struct~e_1 ;…;e_n ~\End` then :math:`S/p=~\Struct~e_1 /p;…;e_n /p ~\End` + where :math:`e/p` is defined as follows (note that opaque definitions are processed + as assumptions): + + + :math:`\Def{}{c}{t}{T}/p = \Def{}{c}{t}{T}` + + :math:`\Assum{}{c}{U}/p = \Def{}{c}{p.c}{U}` + + :math:`\ModS{X}{S}/p = \ModA{X}{p.X}` + + :math:`\ModA{X}{p′}/p = \ModA{X}{p′}` + + :math:`\Ind{}{Γ_P}{Γ_C}{Γ_I}/p = \Indp{}{Γ_P}{Γ_C}{Γ_I}{p}` + + :math:`\Indpstr{}{Γ_P}{Γ_C}{Γ_I}{p'}{p} = \Indp{}{Γ_P}{Γ_C}{Γ_I}{p'}` + ++ if :math:`S \lra \Functor(X:S′)~S″` then :math:`S/p=S` + + +The notation :math:`\Indp{}{Γ_P}{Γ_C}{Γ_I}{p}` +denotes an inductive definition that is definitionally equal to the +inductive definition in the module denoted by the path :math:`p`. All rules +which have :math:`\Ind{}{Γ_P}{Γ_C}{Γ_I}` as premises are also valid for +:math:`\Indp{}{Γ_P}{Γ_C}{Γ_I}{p}`. We give the formation rule for +:math:`\Indp{}{Γ_P}{Γ_C}{Γ_I}{p}` +below as well as the equality rules on inductive types and +constructors. + +The module subtyping rules: + +.. inference:: MSUB-STR + + \begin{array}{c} + \WS{E;e_1 ;…;e_n }{e_{σ(i)}}{e'_i ~\for~ i=1..m} \\ + σ : \{1… m\} → \{1… n\} ~\injective + \end{array} + -------------------------- + \WS{E}{\Struct~e_1 ;…;e_n ~\End}{~\Struct~e'_1 ;…;e'_m ~\End} + +.. inference:: MSUB-FUN + + \WS{E}{\ovl{S_1'}}{\ovl{S_1}} + \WS{E; \ModS{X}{S_1'}}{\ovl{S_2}}{\ovl{S_2'}} + -------------------------- + E[] ⊢ \Functor(X:S_1 ) S_2 <: \Functor(X:S_1') S_2' + + +Structure element subtyping rules: + +.. inference:: ASSUM-ASSUM + + E[] ⊢ T_1 ≤_{βδιζη} T_2 + -------------------------- + \WS{E}{\Assum{}{c}{T_1 }}{\Assum{}{c}{T_2 }} + +.. inference:: DEF-ASSUM + + E[] ⊢ T_1 ≤_{βδιζη} T_2 + -------------------------- + \WS{E}{\Def{}{c}{t}{T_1 }}{\Assum{}{c}{T_2 }} + +.. inference:: ASSUM-DEF + + E[] ⊢ T_1 ≤_{βδιζη} T_2 + E[] ⊢ c =_{βδιζη} t_2 + -------------------------- + \WS{E}{\Assum{}{c}{T_1 }}{\Def{}{c}{t_2 }{T_2 }} + +.. inference:: DEF-DEF + + E[] ⊢ T_1 ≤_{βδιζη} T_2 + E[] ⊢ t_1 =_{βδιζη} t_2 + -------------------------- + \WS{E}{\Def{}{c}{t_1 }{T_1 }}{\Def{}{c}{t_2 }{T_2 }} + +.. inference:: IND-IND + + E[] ⊢ Γ_P =_{βδιζη} Γ_P' + E[Γ_P ] ⊢ Γ_C =_{βδιζη} Γ_C' + E[Γ_P ;Γ_C ] ⊢ Γ_I =_{βδιζη} Γ_I' + -------------------------- + \WS{E}{\ind{Γ_P}{Γ_C}{Γ_I}}{\ind{Γ_P'}{Γ_C'}{Γ_I'}} + +.. inference:: INDP-IND + + E[] ⊢ Γ_P =_{βδιζη} Γ_P' + E[Γ_P ] ⊢ Γ_C =_{βδιζη} Γ_C' + E[Γ_P ;Γ_C ] ⊢ Γ_I =_{βδιζη} Γ_I' + -------------------------- + \WS{E}{\Indp{}{Γ_P}{Γ_C}{Γ_I}{p}}{\ind{Γ_P'}{Γ_C'}{Γ_I'}} + +.. inference:: INDP-INDP + + \begin{array}{c} + E[] ⊢ Γ_P =_{βδιζη} Γ_P' + E[Γ_P ] ⊢ Γ_C =_{βδιζη} Γ_C' \\ + E[Γ_P ;Γ_C ] ⊢ Γ_I =_{βδιζη} Γ_I' + E[] ⊢ p =_{βδιζη} p' + \end{array} + -------------------------- + \WS{E}{\Indp{}{Γ_P}{Γ_C}{Γ_I}{p}}{\Indp{}{Γ_P'}{Γ_C'}{Γ_I'}{p'}} + +.. inference:: MOD-MOD + + \WS{E}{S_1}{S_2} + -------------------------- + \WS{E}{\ModS{X}{S_1 }}{\ModS{X}{S_2 }} + +.. inference:: ALIAS-MOD + + E[] ⊢ p : S_1 + \WS{E}{S_1}{S_2} + -------------------------- + \WS{E}{\ModA{X}{p}}{\ModS{X}{S_2 }} + +.. inference:: MOD-ALIAS + + E[] ⊢ p : S_2 + \WS{E}{S_1}{S_2} + E[] ⊢ X =_{βδιζη} p + -------------------------- + \WS{E}{\ModS{X}{S_1 }}{\ModA{X}{p}} + +.. inference:: ALIAS-ALIAS + + E[] ⊢ p_1 =_{βδιζη} p_2 + -------------------------- + \WS{E}{\ModA{X}{p_1 }}{\ModA{X}{p_2 }} + +.. inference:: MODTYPE-MODTYPE + + \WS{E}{S_1}{S_2} + \WS{E}{S_2}{S_1} + -------------------------- + \WS{E}{\ModType{Y}{S_1 }}{\ModType{Y}{S_2 }} + + +New environment formation rules + + +.. inference:: WF-MOD1 + + \WF{E}{} + \WFT{E}{S} + -------------------------- + WF(E; \ModS{X}{S})[] + +.. inference:: WF-MOD2 + + \WS{E}{S_2}{S_1} + \WF{E}{} + \WFT{E}{S_1} + \WFT{E}{S_2} + -------------------------- + \WF{E; \Mod{X}{S_1}{S_2}}{} + +.. inference:: WF-ALIAS + + \WF{E}{} + E[] ⊢ p : S + -------------------------- + \WF{E, \ModA{X}{p}}{} + +.. inference:: WF-MODTYPE + + \WF{E}{} + \WFT{E}{S} + -------------------------- + \WF{E, \ModType{Y}{S}}{} + +.. inference:: WF-IND + + \begin{array}{c} + \WF{E;\ind{Γ_P}{Γ_C}{Γ_I}}{} \\ + E[] ⊢ p:~\Struct~e_1 ;…;e_n ;\ind{Γ_P'}{Γ_C'}{Γ_I'};… ~\End : \\ + E[] ⊢ \ind{Γ_P'}{Γ_C'}{Γ_I'} <: \ind{Γ_P}{Γ_C}{Γ_I} + \end{array} + -------------------------- + \WF{E; \Indp{}{Γ_P}{Γ_C}{Γ_I}{p} }{} + + +Component access rules + + +.. inference:: ACC-TYPE1 + + E[Γ] ⊢ p :~\Struct~e_1 ;…;e_i ;\Assum{}{c}{T};… ~\End + -------------------------- + E[Γ] ⊢ p.c : T + +.. inference:: ACC-TYPE2 + + E[Γ] ⊢ p :~\Struct~e_1 ;…;e_i ;\Def{}{c}{t}{T};… ~\End + -------------------------- + E[Γ] ⊢ p.c : T + +Notice that the following rule extends the delta rule defined in section :ref:`Conversion-rules` + +.. inference:: ACC-DELTA + + E[Γ] ⊢ p :~\Struct~e_1 ;…;e_i ;\Def{}{c}{t}{U};… ~\End + -------------------------- + E[Γ] ⊢ p.c \triangleright_δ t + +In the rules below we assume +:math:`Γ_P` is :math:`[p_1 :P_1 ;…;p_r :P_r ]`, +:math:`Γ_I` is :math:`[I_1 :A_1 ;…;I_k :A_k ]`, +and :math:`Γ_C` is :math:`[c_1 :C_1 ;…;c_n :C_n ]`. + +.. inference:: ACC-IND1 + + E[Γ] ⊢ p :~\Struct~e_1 ;…;e_i ;\ind{Γ_P}{Γ_C}{Γ_I};… ~\End + -------------------------- + E[Γ] ⊢ p.I_j : (p_1 :P_1 )…(p_r :P_r )A_j + +.. inference:: ACC-IND2 + + E[Γ] ⊢ p :~\Struct~e_1 ;…;e_i ;\ind{Γ_P}{Γ_C}{Γ_I};… ~\End + -------------------------- + E[Γ] ⊢ p.c_m : (p_1 :P_1 )…(p_r :P_r )C_m I_j (I_j~p_1 …p_r )_{j=1… k} + +.. inference:: ACC-INDP1 + + E[] ⊢ p :~\Struct~e_1 ;…;e_i ; \Indp{}{Γ_P}{Γ_C}{Γ_I}{p'} ;… ~\End + -------------------------- + E[] ⊢ p.I_i \triangleright_δ p'.I_i + +.. inference:: ACC-INDP2 + + E[] ⊢ p :~\Struct~e_1 ;…;e_i ; \Indp{}{Γ_P}{Γ_C}{Γ_I}{p'} ;… ~\End + -------------------------- + E[] ⊢ p.c_i \triangleright_δ p'.c_i diff --git a/doc/sphinx/license.rst b/doc/sphinx/license.rst new file mode 100644 index 0000000000..55c6d988f0 --- /dev/null +++ b/doc/sphinx/license.rst @@ -0,0 +1,7 @@ +License +------- + +This material (the Coq Reference Manual) may be distributed only subject to the +terms and conditions set forth in the Open Publication License, v1.0 or later +(the latest version is presently available at +http://www.opencontent.org/openpub). Options A and B are not elected. diff --git a/doc/sphinx/practical-tools/coq-commands.rst b/doc/sphinx/practical-tools/coq-commands.rst new file mode 100644 index 0000000000..bdda35fcc0 --- /dev/null +++ b/doc/sphinx/practical-tools/coq-commands.rst @@ -0,0 +1,306 @@ +.. _thecoqcommands: + +The |Coq| commands +==================== + +There are three |Coq| commands: + ++ ``coqtop``: the |Coq| toplevel (interactive mode); ++ ``coqc``: the |Coq| compiler (batch compilation); ++ ``coqchk``: the |Coq| checker (validation of compiled libraries). + + +The options are (basically) the same for the first two commands, and +roughly described below. You can also look at the ``man`` pages of +``coqtop`` and ``coqc`` for more details. + +.. _interactive-use: + +Interactive use (coqtop) +------------------------ + +In the interactive mode, also known as the |Coq| toplevel, the user can +develop his theories and proofs step by step. The |Coq| toplevel is run +by the command ``coqtop``. + +There are two different binary images of |Coq|: the byte-code one and the +native-code one (if OCaml provides a native-code compiler for +your platform, which is supposed in the following). By default, +``coqtop`` executes the native-code version; run ``coqtop.byte`` to get +the byte-code version. + +The byte-code toplevel is based on an OCaml toplevel (to +allow dynamic linking of tactics). You can switch to the OCaml toplevel +with the command ``Drop.``, and come back to the |Coq| +toplevel with the command ``Coqloop.loop();;``. + +.. flag:: Coqtop Exit On Error + + This option, off by default, causes coqtop to exit with status code + ``1`` if a command produces an error instead of recovering from it. + +Batch compilation (coqc) +------------------------ + +The ``coqc`` command takes a name *file* as argument. Then it looks for a +vernacular file named *file*.v, and tries to compile it into a +*file*.vo file (See :ref:`compiled-files`). + +.. caution:: + + The name *file* should be a regular |Coq| identifier as defined in Section :ref:`lexical-conventions`. + It should contain only letters, digits or underscores (_). For example ``/bar/foo/toto.v`` is valid, + but ``/bar/foo/to-to.v`` is not. + + +Customization at launch time +--------------------------------- + +By resource file +~~~~~~~~~~~~~~~~~~~~~~~ + +When |Coq| is launched, with either ``coqtop`` or ``coqc``, the +resource file ``$XDG_CONFIG_HOME/coq/coqrc.xxx``, if it exists, will +be implicitly prepended to any document read by Coq, whether it is an +interactive session or a file to compile. Here, ``$XDG_CONFIG_HOME`` +is the configuration directory of the user (by default it's ``~/.config``) +and ``xxx`` is the version number (e.g. 8.8). If +this file is not found, then the file ``$XDG_CONFIG_HOME/coqrc`` is +searched. If not found, it is the file ``~/.coqrc.xxx`` which is searched, +and, if still not found, the file ``~/.coqrc``. If the latter is also +absent, no resource file is loaded. +You can also specify an arbitrary name for the resource file +(see option ``-init-file`` below). + +The resource file may contain, for instance, ``Add LoadPath`` commands to add +directories to the load path of |Coq|. It is possible to skip the +loading of the resource file with the option ``-q``. + +.. _customization-by-environment-variables: + +By environment variables +~~~~~~~~~~~~~~~~~~~~~~~~~ + +Load path can be specified to the |Coq| system by setting up ``$COQPATH`` +environment variable. It is a list of directories separated by +``:`` (``;`` on Windows). |Coq| will also honor ``$XDG_DATA_HOME`` and +``$XDG_DATA_DIRS`` (see Section :ref:`libraries-and-filesystem`). + +Some |Coq| commands call other |Coq| commands. In this case, they look for +the commands in directory specified by ``$COQBIN``. If this variable is +not set, they look for the commands in the executable path. + +.. _COQ_COLORS: + +The ``$COQ_COLORS`` environment variable can be used to specify the set +of colors used by ``coqtop`` to highlight its output. It uses the same +syntax as the ``$LS_COLORS`` variable from GNU’s ls, that is, a colon-separated +list of assignments of the form :n:`name={*; attr}` where +``name`` is the name of the corresponding highlight tag and each ``attr`` is an +ANSI escape code. The list of highlight tags can be retrieved with the +``-list-tags`` command-line option of ``coqtop``. + +The string uses ANSI escape codes to represent attributes. For example: + + ``export COQ_COLORS=”diff.added=4;48;2;0;0;240:diff.removed=41”`` + +sets the highlights for added text in diffs to underlined (the 4) with a background RGB +color (0, 0, 240) and for removed text in diffs to a red background. +Note that if you specify ``COQ_COLORS``, the predefined attributes are ignored. + + +.. _command-line-options: + +By command line options +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +The following command-line options are recognized by the commands ``coqc`` +and ``coqtop``, unless stated otherwise: + +:-I *directory*, -include *directory*: Add physical path *directory* + to the OCaml loadpath. + + .. seealso:: + + :ref:`names-of-libraries` and the + command Declare ML Module Section :ref:`compiled-files`. +:-Q *directory* dirpath: Add physical path *directory* to the list of + directories where |Coq| looks for a file and bind it to the logical + directory *dirpath*. The subdirectory structure of *directory* is + recursively available from |Coq| using absolute names (extending the + dirpath prefix) (see Section :ref:`qualified-names`).Note that only those + subdirectories and files which obey the lexical conventions of what is + an :n:`@ident` are taken into account. Conversely, the + underlying file systems or operating systems may be more restrictive + than |Coq|. While Linux’s ext4 file system supports any |Coq| recursive + layout (within the limit of 255 bytes per filename), the default on + NTFS (Windows) or HFS+ (MacOS X) file systems is on the contrary to + disallow two files differing only in the case in the same directory. + + .. seealso:: Section :ref:`names-of-libraries`. +:-R *directory* dirpath: Do as -Q *directory* dirpath but make the + subdirectory structure of *directory* recursively visible so that the + recursive contents of physical *directory* is available from |Coq| using + short or partially qualified names. + + .. seealso:: Section :ref:`names-of-libraries`. +:-top dirpath: Set the toplevel module name to dirpath instead of Top. + Not valid for `coqc` as the toplevel module name is inferred from the + name of the output file. +:-exclude-dir *directory*: Exclude any subdirectory named *directory* + while processing options such as -R and -Q. By default, only the + conventional version control management directories named CVS + and_darcs are excluded. +:-nois: Start from an empty state instead of loading the Init.Prelude + module. +:-init-file *file*: Load *file* as the resource file instead of + loading the default resource file from the standard configuration + directories. +:-q: Do not to load the default resource file. +:-load-ml-source *file*: Load the OCaml source file *file*. +:-load-ml-object *file*: Load the OCaml object file *file*. +:-l *file*, -load-vernac-source *file*: Load and execute the |Coq| + script from *file.v*. +:-lv *file*, -load-vernac-source-verbose *file*: Load and execute the + |Coq| script from *file.v*. Write its contents to the standard output as + it is executed. +:-load-vernac-object dirpath: Load |Coq| compiled library dirpath. This + is equivalent to runningRequire dirpath. +:-require dirpath: Load |Coq| compiled library dirpath and import it. + This is equivalent to running Require Import dirpath. +:-batch: Exit just after argument parsing. Available for ``coqtop`` only. +:-compile *file.v*: Deprecated; use ``coqc`` instead. Compile file *file.v* into *file.vo*. This option + implies -batch (exit just after argument parsing). It is available only + for `coqtop`, as this behavior is the purpose of ``coqc``. +:-compile-verbose *file.v*: Deprecated. Use ``coqc -verbose``. Same as -compile but also output the + content of *file.v* as it is compiled. +:-verbose: Output the content of the input file as it is compiled. + This option is available for ``coqc`` only; it is the counterpart of + -compile-verbose. +:-w (all|none|w₁,…,wₙ): Configure the display of warnings. This + option expects all, none or a comma-separated list of warning names or + categories (see Section :ref:`controlling-display`). +:-color (on|off|auto): *Coqtop only*. Enable or disable color output. + Default is auto, meaning color is shown only if + the output channel supports ANSI escape sequences. +:-diffs (on|off|removed): *Coqtop only*. Controls highlighting of differences + between proof steps. ``on`` highlights added tokens, ``removed`` highlights both added and + removed tokens. Requires that ``–color`` is enabled. (see Section + :ref:`showing_diffs`). +:-beautify: Pretty-print each command to *file.beautified* when + compiling *file.v*, in order to get old-fashioned + syntax/definitions/notations. +:-emacs, -ide-slave: Start a special toplevel to communicate with a + specific IDE. +:-impredicative-set: Change the logical theory of |Coq| by declaring the + sort Set impredicative. + + .. warning:: + + This is known to be inconsistent with some + standard axioms of classical mathematics such as the functional + axiom of choice or the principle of description. +:-type-in-type: Collapse the universe hierarchy of |Coq|. + + .. warning:: This makes the logic inconsistent. +:-mangle-names *ident*: *Experimental.* Do not depend on this option. Replace + Coq's auto-generated name scheme with names of the form *ident0*, *ident1*, + etc. Within Coq, the flag :flag:`Mangle Names` turns this behavior on, + and the :opt:`Mangle Names Prefix` option sets the prefix to use. This feature + is intended to be used as a linter for developments that want to be robust to + changes in the auto-generated name scheme. The options are provided to + facilitate tracking down problems. +:-set *string*: Enable flags and set options. *string* should be + ``Option Name=value``, the value is interpreted according to the + type of the option. For flags ``Option Name`` is equivalent to + ``Option Name=true``. For instance ``-set "Universe Polymorphism"`` + will enable :flag:`Universe Polymorphism`. Note that the quotes are + shell syntax, Coq does not see them. +:-unset *string*: As ``-set`` but used to disable options and flags. +:-compat *version*: Attempt to maintain some backward-compatibility + with a previous version. +:-dump-glob *file*: Dump references for global names in file *file* + (to be used by coqdoc, see :ref:`coqdoc`). By default, if *file.v* is being + compiled, *file.glob* is used. +:-no-glob: Disable the dumping of references for global names. +:-image *file*: Set the binary image to be used by ``coqc`` to be *file* + instead of the standard one. Not of general use. +:-bindir *directory*: Set the directory containing |Coq| binaries to be + used by ``coqc``. It is equivalent to doing export COQBIN= *directory* + before launching ``coqc``. +:-where: Print the location of |Coq|’s standard library and exit. +:-config: Print the locations of |Coq|’s binaries, dependencies, and + libraries, then exit. +:-filteropts: Print the list of command line arguments that `coqtop` has + recognized as options and exit. +:-v: Print |Coq|’s version and exit. +:-list-tags: Print the highlight tags known by |Coq| as well as their + currently associated color and exit. +:-h, --help: Print a short usage and exit. + +Compiled libraries checker (coqchk) +---------------------------------------- + +The ``coqchk`` command takes a list of library paths as argument, described either +by their logical name or by their physical filename, hich must end in ``.vo``. The +corresponding compiled libraries (``.vo`` files) are searched in the path, +recursively processing the libraries they depend on. The content of all these +libraries is then type checked. The effect of ``coqchk`` is only to return with +normal exit code in case of success, and with positive exit code if an error has +been found. Error messages are not deemed to help the user understand what is +wrong. In the current version, it does not modify the compiled libraries to mark +them as successfully checked. + +Note that non-logical information is not checked. By logical +information, we mean the type and optional body associated to names. +It excludes for instance anything related to the concrete syntax of +objects (customized syntax rules, association between short and long +names), implicit arguments, etc. + +This tool can be used for several purposes. One is to check that a +compiled library provided by a third-party has not been forged and +that loading it cannot introduce inconsistencies [#]_. Another point is +to get an even higher level of security. Since ``coqtop`` can be extended +with custom tactics, possibly ill-typed code, it cannot be guaranteed +that the produced compiled libraries are correct. ``coqchk`` is a +standalone verifier, and thus it cannot be tainted by such malicious +code. + +Command-line options ``-Q``, ``-R``, ``-where`` and ``-impredicative-set`` are supported +by ``coqchk`` and have the same meaning as for ``coqtop``. As there is no notion of +relative paths in object files ``-Q`` and ``-R`` have exactly the same meaning. + +:-norec *module*: Check *module* but do not check its dependencies. +:-admit *module*: Do not check *module* and any of its dependencies, + unless explicitly required. +:-o: At exit, print a summary about the context. List the names of all + assumptions and variables (constants without body). +:-silent: Do not write progress information to the standard output. + +Environment variable ``$COQLIB`` can be set to override the location of +the standard library. + +The algorithm for deciding which modules are checked or admitted is +the following: assuming that ``coqchk`` is called with argument ``M``, option +``-norec N``, and ``-admit A``. Let us write :math:`\overline{S}` for the +set of reflexive transitive dependencies of set :math:`S`. Then: + ++ Modules :math:`C = \overline{M} \backslash \overline{A} \cup M \cup N` are loaded and type checked before being added + to the context. ++ And :math:`M \cup N \backslash C` is the set of modules that are loaded and added to the + context without type checking. Basic integrity checks (checksums) are + nonetheless performed. + +As a rule of thumb, -admit can be used to tell Coq that some libraries +have already been checked. So ``coqchk A B`` can be split in ``coqchk A`` && +``coqchk B -admit A`` without type checking any definition twice. Of +course, the latter is slightly slower since it makes more disk access. +It is also less secure since an attacker might have replaced the +compiled library ``A`` after it has been read by the first command, but +before it has been read by the second command. + +.. [#] Ill-formed non-logical information might for instance bind + Coq.Init.Logic.True to short name False, so apparently False is + inhabited, but using fully qualified names, Coq.Init.Logic.False will + always refer to the absurd proposition, what we guarantee is that + there is no proof of this latter constant. diff --git a/doc/sphinx/practical-tools/coqide.rst b/doc/sphinx/practical-tools/coqide.rst new file mode 100644 index 0000000000..97d86943fb --- /dev/null +++ b/doc/sphinx/practical-tools/coqide.rst @@ -0,0 +1,346 @@ +.. _coqintegrateddevelopmentenvironment: + +|Coq| Integrated Development Environment +======================================== + +The Coq Integrated Development Environment is a graphical tool, to be +used as a user-friendly replacement to `coqtop`. Its main purpose is to +allow the user to navigate forward and backward into a Coq vernacular +file, executing corresponding commands or undoing them respectively. + +|CoqIDE| is run by typing the command `coqide` on the command line. +Without argument, the main screen is displayed with an “unnamed +buffer”, and with a filename as argument, another buffer displaying +the contents of that file. Additionally, `coqide` accepts the same +options as `coqtop`, given in :ref:`thecoqcommands`, the ones having obviously +no meaning for |CoqIDE| being ignored. + +.. _coqide_mainscreen: + + .. image:: ../_static/coqide.png + :alt: |CoqIDE| main screen + +A sample |CoqIDE| main screen, while navigating into a file `Fermat.v`, +is shown in the figure :ref:`CoqIDE main screen <coqide_mainscreen>`. +At the top is a menu bar, and a tool bar +below it. The large window on the left is displaying the various +*script buffers*. The upper right window is the *goal window*, where +goals to be proven are displayed. The lower right window is the *message +window*, where various messages resulting from commands are displayed. +At the bottom is the status bar. + +Managing files and buffers, basic editing +---------------------------------------------- + +In the script window, you may open arbitrarily many buffers to edit. +The *File* menu allows you to open files or create some, save them, +print or export them into various formats. Among all these buffers, +there is always one which is the current *running buffer*, whose name +is displayed on a background in the *processed* color (green by default), which +is the one where Coq commands are currently executed. + +Buffers may be edited as in any text editor, and classical basic +editing commands (Copy/Paste, …) are available in the *Edit* menu. +|CoqIDE| offers only basic editing commands, so if you need more complex +editing commands, you may launch your favorite text editor on the +current buffer, using the *Edit/External Editor* menu. + +Interactive navigation into Coq scripts +-------------------------------------------- + +The running buffer is the one where navigation takes place. The toolbar offers +five basic commands for this. The first one, represented by a down arrow icon, +is for going forward executing one command. If that command is successful, the +part of the script that has been executed is displayed on a background with the +processed color. If that command fails, the error message is displayed in the +message window, and the location of the error is emphasized by an underline in +the error foreground color (red by default). + +In the figure :ref:`CoqIDE main screen <coqide_mainscreen>`, +the running buffer is `Fermat.v`, all commands until +the ``Theorem`` have been already executed, and the user tried to go +forward executing ``Induction n``. That command failed because no such +tactic exists (names of standard tactics are written in lowercase), +and the failing command is underlined. + +Notice that the processed part of the running buffer is not editable. If +you ever want to modify something you have to go backward using the up +arrow tool, or even better, put the cursor where you want to go back +and use the goto button. Unlike with `coqtop`, you should never use +``Undo`` to go backward. + +There are two additional buttons for navigation within the running buffer. The +"down" button with a line goes directly to the end; the "up" button with a line +goes back to the beginning. The handling of errors when using the go-to-the-end +button depends on whether |Coq| is running in asynchronous mode or not (see +Chapter :ref:`asynchronousandparallelproofprocessing`). If it is not running in that mode, execution +stops as soon as an error is found. Otherwise, execution continues, and the +error is marked with an underline in the error foreground color, with a +background in the error background color (pink by default). The same +characterization of error-handling applies when running several commands using +the "goto" button. + +If you ever try to execute a command that runs for a long time +and would like to abort it before it terminates, you may +use the interrupt button (the white cross on a red circle). + +There are other buttons on the |CoqIDE| toolbar: a button to save the running +buffer; a button to close the current buffer (an "X"); buttons to switch among +buffers (left and right arrows); an "information" button; and a "gears" button. + +The "information" button is described in Section :ref:`try-tactics-automatically`. + +The "gears" button submits proof terms to the |Coq| kernel for type checking. +When |Coq| uses asynchronous processing (see Chapter :ref:`asynchronousandparallelproofprocessing`), +proofs may have been completed without kernel-checking of generated proof terms. +The presence of unchecked proof terms is indicated by ``Qed`` statements that +have a subdued *being-processed* color (light blue by default), rather than the +processed color, though their preceding proofs have the processed color. + +Notice that for all these buttons, except for the "gears" button, their operations +are also available in the menu, where their keyboard shortcuts are given. + +.. _try-tactics-automatically: + +Trying tactics automatically +------------------------------ + +The menu Try Tactics provides some features for automatically trying +to solve the current goal using simple tactics. If such a tactic +succeeds in solving the goal, then its text is automatically inserted +into the script. There is finally a combination of these tactics, +called the *proof wizard* which will try each of them in turn. This +wizard is also available as a tool button (the "information" button). The set of +tactics tried by the wizard is customizable in the preferences. + +These tactics are general ones, in particular they do not refer to +particular hypotheses. You may also try specific tactics related to +the goal or one of the hypotheses, by clicking with the right mouse +button on the goal or the considered hypothesis. This is the +“contextual menu on goals” feature, that may be disabled in the +preferences if undesirable. + + +Proof folding +------------------ + +As your script grows bigger and bigger, it might be useful to hide the +proofs of your theorems and lemmas. + +This feature is toggled via the Hide entry of the Navigation menu. The +proof shall be enclosed between ``Proof.`` and ``Qed.``, both with their final +dots. The proof that shall be hidden or revealed is the first one +whose beginning statement (such as ``Theorem``) precedes the insertion +cursor. + + +Vernacular commands, templates +----------------------------------- + +The Templates menu allows using shortcuts to insert vernacular +commands. This is a nice way to proceed if you are not sure of the +syntax of the command you want. + +Moreover, from this menu you can automatically insert templates of complex +commands like ``Fixpoint`` that you can conveniently fill afterwards. + +Queries +------------ + +.. image:: ../_static/coqide-queries.png + :alt: |CoqIDE| queries + +We call *query* any vernacular command that does not change the current state, +such as ``Check``, ``Search``, etc. To run such commands interactively, without +writing them in scripts, |CoqIDE| offers a *query pane*. The query pane can be +displayed on demand by using the ``View`` menu, or using the shortcut ``F1``. +Queries can also be performed by selecting a particular phrase, then choosing an +item from the ``Queries`` menu. The response then appears in the message window. +The image above shows the result after selecting of the phrase +``Nat.mul`` in the script window, and choosing ``Print`` from the ``Queries`` +menu. + + +Compilation +---------------- + +The `Compile` menu offers direct commands to: + ++ compile the current buffer ++ run a compilation using `make` ++ go to the last compilation error ++ create a `Makefile` using `coq_makefile`. + +Customizations +------------------- + +You may customize your environment using the menu Edit/Preferences. A new +window will be displayed, with several customization sections +presented as a notebook. + +The first section is for selecting the text font used for scripts, +goal and message windows. + +The second section is devoted to file management: you may configure +automatic saving of files, by periodically saving the contents into +files named `#f#` for each opened file `f`. You may also activate the +*revert* feature: in case a opened file is modified on the disk by a +third party, |CoqIDE| may read it again for you. Note that in the case +you edited that same file, you will be prompted to choose to either +discard your changes or not. The File charset encoding choice is +described below in :ref:`character-encoding-saved-files`. + +The `Externals` section allows customizing the external commands for +compilation, printing, web browsing. In the browser command, you may +use `%s` to denote the URL to open, for example: +`firefox -remote "OpenURL(%s)"`. + +The `Tactics Wizard` section allows defining the set of tactics that +should be tried, in sequence, to solve the current goal. + +The last section is for miscellaneous boolean settings, such as the +“contextual menu on goals” feature presented in the section +:ref:`Try tactics automatically <try-tactics-automatically>`. + +Notice that these settings are saved in the file `.coqiderc` of your +home directory. + +A Gtk2 accelerator keymap is saved under the name `.coqide.keys`. It +is not recommended to edit this file manually: to modify a given menu +shortcut, go to the corresponding menu item without releasing the +mouse button, press the key you want for the new shortcut, and release +the mouse button afterwards. If your system does not allow it, you may +still edit this configuration file by hand, but this is more involved. + + +Using Unicode symbols +-------------------------- + +|CoqIDE| is based on GTK+ and inherits from it support for Unicode in +its text windows. Consequently a large set of symbols is available for +notations. Furthermore, |CoqIDE| conveniently provides a simple way to +input Unicode characters. + + +Displaying Unicode symbols +~~~~~~~~~~~~~~~~~~~~~~~~~~ + +You just need to define suitable notations as described in the chapter +:ref:`syntaxextensionsandinterpretationscopes`. For example, to use the +mathematical symbols ∀ and ∃, you may define: + +.. coqtop:: in + + Notation "∀ x .. y , P" := (forall x, .. (forall y, P) ..) + (at level 200, x binder, y binder, right associativity) + : type_scope. + Notation "∃ x .. y , P" := (exists x, .. (exists y, P) ..) + (at level 200, x binder, y binder, right associativity) + : type_scope. + +There exists a small set of such notations already defined, in the +file `utf8.v` of Coq library, so you may enable them just by +``Require Import Unicode.Utf8`` inside |CoqIDE|, or equivalently, +by starting |CoqIDE| with ``coqide -l utf8``. + +However, there are some issues when using such Unicode symbols: you of +course need to use a character font which supports them. In the Fonts +section of the preferences, the Preview line displays some Unicode +symbols, so you could figure out if the selected font is OK. Related +to this, one thing you may need to do is choosing whether GTK+ should +use antialiased fonts or not, by setting the environment variable +`GDK_USE_XFT` to 1 or 0 respectively. + + +Bindings for input of Unicode symbols +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +CoqIDE supports a builtin mechanism to input non-ASCII symbols. +For example, to input ``π``, it suffices to type ``\pi`` then press the +combination of key ``Shift+Space`` (default key binding). Often, it +suffices to type a prefix of the latex token, e.g. typing ``\p`` +then ``Shift+Space`` suffices to insert a ``π``. + +For several symbols, ASCII art is also recognized, e.g. ``\->`` for a +right arrow, or ``\>=`` for a greater than or equal sign. + +A larger number of latex tokens are supported by default. The full list +is available here: +https://github.com/coq/coq/blob/master/ide/default_bindings_src.ml + +Custom bindings may be added, as explained further on. + +.. note:: + + It remains possible to input non-ASCII symbols using system-wide + approaches independent of |CoqIDE|. + + +Adding custom bindings +~~~~~~~~~~~~~~~~~~~~~~ + +To extend the default set of bindings, create a file named ``coqide.bindings`` +and place it in the same folder as ``coqide.keys``. On Linux, this would be +the folder ``~/.config/coq``. The file `coqide.bindings` should contain one +binding per line, in the form ``\key value``, followed by an optional priority +integer. (The key and value should not contain any space character.) + +.. example:: + + Here is an example configuration file: + + :: + + \par || + \pi π 1 + \le ≤ 1 + \lambda λ 2 + \lambdas λs + +Above, the priority number 1 on ``\pi`` indicates that the prefix ``\p`` +should resolve to ``\pi``, and not to something else (e.g. ``\par``). +Similarly, the above settings ensure than ``\l`` resolves to ``\le``, +and that ``\la`` resolves to ``\lambda``. + +It can be useful to work with per-project binding files. For this purpose +|CoqIDE| accepts a command line argument of the form +``-unicode-bindings file1,file2,...,fileN``. +Each of the file tokens provided may consists of one of: + + - a path to a custom bindings file, + - the token ``default``, which resolves to the default bindings file, + - the token ``local``, which resolves to the `coqide.bindings` file + stored in the user configuration directory. + +.. warning:: + + If a filename other than the first one includes a "~" to refer + to the home directory, it won't be expanded properly. To work around that + issue, one should not use comas but instead repeat the flag, in the form: + ``-unicode-bindings file1 .. -unicode-bindings fileN``. + +.. note:: + + If two bindings for a same token both have the same priority value + (or both have no priority value set), then the binding considered is + the one from the file that comes first on the command line. + + +.. _character-encoding-saved-files: + +Character encoding for saved files +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +In the Files section of the preferences, the encoding option is +related to the way files are saved. + +If you have no need to exchange files with non UTF-8 aware +applications, it is better to choose the UTF-8 encoding, since it +guarantees that your files will be read again without problems. (This +is because when |CoqIDE| reads a file, it tries to automatically detect +its character encoding.) + +If you choose something else than UTF-8, then missing characters will +be written encoded by `\x{....}` or `\x{........}` where each dot is +an hexadecimal digit: the number between braces is the hexadecimal +Unicode index for the missing character. diff --git a/doc/sphinx/practical-tools/utilities.rst b/doc/sphinx/practical-tools/utilities.rst new file mode 100644 index 0000000000..8346b72cb9 --- /dev/null +++ b/doc/sphinx/practical-tools/utilities.rst @@ -0,0 +1,1052 @@ +.. _utilities: + +--------------------- + Utilities +--------------------- + +The distribution provides utilities to simplify some tedious works +beside proof development, tactics writing or documentation. + + +Using Coq as a library +---------------------- + +In previous versions, ``coqmktop`` was used to build custom +toplevels - for example for better debugging or custom static +linking. Nowadays, the preferred method is to use ``ocamlfind``. + +The most basic custom toplevel is built using: + +:: + + % ocamlfind ocamlopt -thread -rectypes -linkall -linkpkg \ + -package coq.toplevel \ + topbin/coqtop_bin.ml -o my_toplevel.native + + +For example, to statically link |Ltac|, you can just do: + +:: + + % ocamlfind ocamlopt -thread -rectypes -linkall -linkpkg \ + -package coq.toplevel,coq.plugins.ltac \ + topbin/coqtop_bin.ml -o my_toplevel.native + +and similarly for other plugins. + +Building a |Coq| project +------------------------ + +As of today it is possible to build Coq projects using two tools: + +- coq_makefile, which is distributed by Coq and is based on generating a makefile, +- Dune, the standard OCaml build tool, which, since version 1.9, supports building Coq libraries. + +Building a |Coq| project with coq_makefile +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +The majority of |Coq| projects are very similar: a collection of ``.v`` +files and eventually some ``.ml`` ones (a |Coq| plugin). The main piece of +metadata needed in order to build the project are the command line +options to ``coqc`` (e.g. ``-R``, ``Q``, ``-I``, see :ref:`command +line options <command-line-options>`). Collecting the list of files +and options is the job of the ``_CoqProject`` file. + +A simple example of a ``_CoqProject`` file follows: + +:: + + -R theories/ MyCode + -arg -w + -arg all + theories/foo.v + theories/bar.v + -I src/ + src/baz.ml4 + src/bazaux.ml + src/qux_plugin.mlpack + +where options ``-R``, ``-Q`` and ``-I`` are natively recognized, as well as +file names. The lines of the form ``-arg foo`` are used in order to tell +to literally pass an argument ``foo`` to ``coqc``: in the +example, this allows to pass the two-word option ``-w all`` (see +:ref:`command line options <command-line-options>`). + +Currently, both |CoqIDE| and Proof-General (version ≥ ``4.3pre``) +understand ``_CoqProject`` files and invoke |Coq| with the desired options. + +The ``coq_makefile`` utility can be used to set up a build infrastructure +for the |Coq| project based on makefiles. The recommended way of +invoking ``coq_makefile`` is the following one: + +:: + + coq_makefile -f _CoqProject -o CoqMakefile + + +Such command generates the following files: + +CoqMakefile + is a generic makefile for ``GNU Make`` that provides + targets to build the project (both ``.v`` and ``.ml*`` files), to install it + system-wide in the ``coq-contrib`` directory (i.e. where |Coq| is installed) + as well as to invoke coqdoc to generate HTML documentation. + +CoqMakefile.conf + contains make variables assignments that reflect + the contents of the ``_CoqProject`` file as well as the path relevant to + |Coq|. + + +An optional file ``CoqMakefile.local`` can be provided by the user in order to +extend ``CoqMakefile``. In particular one can declare custom actions to be +performed before or after the build process. Similarly one can customize the +install target or even provide new targets. Extension points are documented in +paragraph :ref:`coqmakefilelocal`. + +The extensions of the files listed in ``_CoqProject`` is used in order to +decide how to build them. In particular: + + ++ |Coq| files must use the ``.v`` extension ++ |OCaml| files must use the ``.ml`` or ``.mli`` extension ++ |OCaml| files that require pre processing for syntax + extensions (like ``VERNAC EXTEND``) must use the ``.ml4`` extension ++ In order to generate a plugin one has to list all |OCaml| + modules (i.e. ``Baz`` for ``baz.ml``) in a ``.mlpack`` file (or ``.mllib`` + file). + + +The use of ``.mlpack`` files has to be preferred over ``.mllib`` files, +since it results in a “packed” plugin: All auxiliary modules (as +``Baz`` and ``Bazaux``) are hidden inside the plugin’s "namespace" +(``Qux_plugin``). This reduces the chances of begin unable to load two +distinct plugins because of a clash in their auxiliary module names. + +.. _coqmakefilelocal: + +CoqMakefile.local ++++++++++++++++++ + +The optional file ``CoqMakefile.local`` is included by the generated +file ``CoqMakefile``. It can contain two kinds of directives. + +**Variable assignment** + +The variable must belong to the variables listed in the ``Parameters`` +section of the generated makefile. +Here we describe only few of them. + +:CAMLPKGS: + can be used to specify third party findlib packages, and is + passed to the OCaml compiler on building or linking of modules. Eg: + ``-package yojson``. +:CAMLFLAGS: + can be used to specify additional flags to the |OCaml| + compiler, like ``-bin-annot`` or ``-w``.... +:COQC, COQDEP, COQDOC: + can be set in order to use alternative binaries + (e.g. wrappers) +:COQ_SRC_SUBDIRS: + can be extended by including other paths in which ``*.cm*`` files + are searched. For example ``COQ_SRC_SUBDIRS+=user-contrib/Unicoq`` + lets you build a plugin containing OCaml code that depends on the + OCaml code of ``Unicoq`` +:COQFLAGS: + override the flags passed to ``coqc``. By default ``-q``. +:COQEXTRAFLAGS: + extend the flags passed to ``coqc`` +:COQCHKFLAGS: + override the flags passed to ``coqchk``. By default ``-silent -o``. +:COQCHKEXTRAFLAGS: + extend the flags passed to ``coqchk`` +:COQDOCFLAGS: + override the flags passed to ``coqdoc``. By default ``-interpolate -utf8``. +:COQDOCEXTRAFLAGS: + extend the flags passed to ``coqdoc`` + +**Rule extension** + +The following makefile rules can be extended. + +.. example:: + + :: + + pre-all:: + echo "This line is print before making the all target" + install-extra:: + cp ThisExtraFile /there/it/goes + +``pre-all::`` + run before the ``all`` target. One can use this to configure + the project, or initialize sub modules or check dependencies are met. + +``post-all::`` + run after the ``all`` target. One can use this to run a test + suite, or compile extracted code. + +``install-extra::`` + run after ``install``. One can use this to install extra files. + +``install-doc::`` + One can use this to install extra doc. + +``uninstall::`` + \ + +``uninstall-doc::`` + \ + +``clean::`` + \ + +``cleanall::`` + \ + +``archclean::`` + \ + +``merlin-hook::`` + One can append lines to the generated ``.merlin`` file extending this + target. + +Timing targets and performance testing +++++++++++++++++++++++++++++++++++++++ + +The generated ``Makefile`` supports the generation of two kinds of timing +data: per-file build-times, and per-line times for an individual file. + +The following targets and Makefile variables allow collection of per- +file timing data: + + ++ ``TIMED=1`` + passing this variable will cause ``make`` to emit a line + describing the user-space build-time and peak memory usage for each + file built. + + .. note:: + On ``Mac OS``, this works best if you’ve installed ``gnu-time``. + + .. example:: + + For example, the output of ``make TIMED=1`` may look like + this: + + :: + + COQDEP Fast.v + COQDEP Slow.v + COQC Slow.v + Slow (user: 0.34 mem: 395448 ko) + COQC Fast.v + Fast (user: 0.01 mem: 45184 ko) + ++ ``pretty-timed`` + this target stores the output of ``make TIMED=1`` into + ``time-of-build.log``, and displays a table of the times, sorted from + slowest to fastest, which is also stored in ``time-of-build-pretty.log``. + If you want to construct the ``log`` for targets other than the default + one, you can pass them via the variable ``TGTS``, e.g., ``make pretty-timed + TGTS="a.vo b.vo"``. + + .. :: + This target requires ``python`` to build the table. + + .. note:: + This target will *append* to the timing log; if you want a + fresh start, you must remove the ``filetime-of-build.log`` or + ``run make cleanall``. + + .. example:: + + For example, the output of ``make pretty-timed`` may look like this: + + :: + + COQDEP Fast.v + COQDEP Slow.v + COQC Slow.v + Slow (user: 0.36 mem: 393912 ko) + COQC Fast.v + Fast (user: 0.05 mem: 45992 ko) + Time | File Name + -------------------- + 0m00.41s | Total + -------------------- + 0m00.36s | Slow + 0m00.05s | Fast + + ++ ``print-pretty-timed-diff`` + this target builds a table of timing changes between two compilations; run + ``make make-pretty-timed-before`` to build the log of the “before” times, + and run ``make make-pretty-timed-after`` to build the log of the “after” + times. The table is printed on the command line, and stored in + ``time-of-build-both.log``. This target is most useful for profiling the + difference between two commits in a repository. + + .. note:: + This target requires ``python`` to build the table. + + .. note:: + The ``make-pretty-timed-before`` and ``make-pretty-timed-after`` targets will + *append* to the timing log; if you want a fresh start, you must remove + the files ``time-of-build-before.log`` and ``time-of-build-after.log`` or run + ``make cleanall`` *before* building either the “before” or “after” + targets. + + .. note:: + The table will be sorted first by absolute time + differences rounded towards zero to a whole-number of seconds, then by + times in the “after” column, and finally lexicographically by file + name. This will put the biggest changes in either direction first, and + will prefer sorting by build-time over subsecond changes in build time + (which are frequently noise); lexicographic sorting forces an order on + files which take effectively no time to compile. + + .. example:: + + For example, the output table from + ``make print-pretty-timed-diff`` may look like this: + + :: + + After | File Name | Before || Change | % Change + -------------------------------------------------------- + 0m00.39s | Total | 0m00.35s || +0m00.03s | +11.42% + -------------------------------------------------------- + 0m00.37s | Slow | 0m00.01s || +0m00.36s | +3600.00% + 0m00.02s | Fast | 0m00.34s || -0m00.32s | -94.11% + + +The following targets and ``Makefile`` variables allow collection of per- +line timing data: + + ++ ``TIMING=1`` + passing this variable will cause ``make`` to use ``coqc -time`` to + write to a ``.v.timing`` file for each ``.v`` file compiled, which contains + line-by-line timing information. + + .. example:: + + For example, running ``make all TIMING=1`` may result in a file like this: + + :: + + Chars 0 - 26 [Require~Coq.ZArith.BinInt.] 0.157 secs (0.128u,0.028s) + Chars 27 - 68 [Declare~Reduction~comp~:=~vm_c...] 0. secs (0.u,0.s) + Chars 69 - 162 [Definition~foo0~:=~Eval~comp~i...] 0.153 secs (0.136u,0.019s) + Chars 163 - 208 [Definition~foo1~:=~Eval~comp~i...] 0.239 secs (0.236u,0.s) + ++ ``print-pretty-single-time-diff`` + + :: + + print-pretty-single-time-diff BEFORE=path/to/file.v.before-timing AFTER=path/to/file.v.after-timing + + this target will make a sorted table of the per-line timing differences + between the timing logs in the ``BEFORE`` and ``AFTER`` files, display it, and + save it to the file specified by the ``TIME_OF_PRETTY_BUILD_FILE`` variable, + which defaults to ``time-of-build-pretty.log``. + To generate the ``.v.before-timing`` or ``.v.after-timing`` files, you should + pass ``TIMING=before`` or ``TIMING=after`` rather than ``TIMING=1``. + + .. note:: + The sorting used here is the same as in the ``print-pretty-timed -diff`` target. + + .. note:: + This target requires python to build the table. + + .. example:: + + For example, running ``print-pretty-single-time-diff`` might give a table like this: + + :: + + After | Code | Before || Change | % Change + --------------------------------------------------------------------------------------------------- + 0m00.50s | Total | 0m04.17s || -0m03.66s | -87.96% + --------------------------------------------------------------------------------------------------- + 0m00.145s | Chars 069 - 162 [Definition~foo0~:=~Eval~comp~i...] | 0m00.192s || -0m00.04s | -24.47% + 0m00.126s | Chars 000 - 026 [Require~Coq.ZArith.BinInt.] | 0m00.143s || -0m00.01s | -11.88% + N/A | Chars 027 - 068 [Declare~Reduction~comp~:=~nati...] | 0m00.s || +0m00.00s | N/A + 0m00.s | Chars 027 - 068 [Declare~Reduction~comp~:=~vm_c...] | N/A || +0m00.00s | N/A + 0m00.231s | Chars 163 - 208 [Definition~foo1~:=~Eval~comp~i...] | 0m03.836s || -0m03.60s | -93.97% + + ++ ``all.timing.diff``, ``path/to/file.v.timing.diff`` + The ``path/to/file.v.timing.diff`` target will make a ``.v.timing.diff`` file for + the corresponding ``.v`` file, with a table as would be generated by + the ``print-pretty-single-time-diff`` target; it depends on having already + made the corresponding ``.v.before-timing`` and ``.v.after-timing`` files, + which can be made by passing ``TIMING=before`` and ``TIMING=after``. + The ``all.timing.diff`` target will make such timing difference files for + all of the ``.v`` files that the ``Makefile`` knows about. It will fail if + some ``.v.before-timing`` or ``.v.after-timing`` files don’t exist. + + .. note:: + This target requires python to build the table. + + +Reusing/extending the generated Makefile +++++++++++++++++++++++++++++++++++++++++ + +Including the generated makefile with an include directive is +discouraged. The contents of this file, including variable names and +status of rules shall change in the future. Users are advised to +include ``Makefile.conf`` or call a target of the generated Makefile as in +``make -f Makefile target`` from another Makefile. + +One way to get access to all targets of the generated ``CoqMakefile`` is to +have a generic target for invoking unknown targets. + +.. example:: + + :: + + # KNOWNTARGETS will not be passed along to CoqMakefile + KNOWNTARGETS := CoqMakefile extra-stuff extra-stuff2 + # KNOWNFILES will not get implicit targets from the final rule, and so + # depending on them won't invoke the submake + # Warning: These files get declared as PHONY, so any targets depending + # on them always get rebuilt + KNOWNFILES := Makefile _CoqProject + + .DEFAULT_GOAL := invoke-coqmakefile + + CoqMakefile: Makefile _CoqProject + $(COQBIN)coq_makefile -f _CoqProject -o CoqMakefile + + invoke-coqmakefile: CoqMakefile + $(MAKE) --no-print-directory -f CoqMakefile $(filter-out $(KNOWNTARGETS),$(MAKECMDGOALS)) + + .PHONY: invoke-coqmakefile $(KNOWNFILES) + + #################################################################### + ## Your targets here ## + #################################################################### + + # This should be the last rule, to handle any targets not declared above + %: invoke-coqmakefile + @true + + + +Building a subset of the targets with ``-j`` +++++++++++++++++++++++++++++++++++++++++++++ + +To build, say, two targets foo.vo and bar.vo in parallel one can use +``make only TGTS="foo.vo bar.vo" -j``. + +.. note:: + + ``make foo.vo bar.vo -j`` has a different meaning for the make + utility, in particular it may build a shared prerequisite twice. + + +.. note:: + + For users of coq_makefile with version < 8.7 + + + Support for "subdirectory" is deprecated. To perform actions before + or after the build (like invoking ``make`` on a subdirectory) one can hook + in pre-all and post-all extension points. + + ``-extra-phony`` and ``-extra`` are deprecated. To provide additional target + (``.PHONY`` or not) please use ``CoqMakefile.local``. + + + +Building a |Coq| project with Dune +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. note:: + + The canonical documentation for the Coq Dune extension is + maintained upstream; please refer to the `Dune manual + <https://dune.readthedocs.io/>`_ for up-to-date information. + +Building a Coq project with Dune requires setting up a Dune project +for your files. This involves adding a ``dune-project`` and +``pkg.opam`` file to the root (``pkg.opam`` can be empty), and then +providing ``dune`` files in the directories your ``.v`` files are +placed. For the experimental version "0.1" of the Coq Dune language, +|Coq| library stanzas look like: + +.. code:: scheme + + (coqlib + (name <module_prefix>) + (public_name <package.lib_name>) + (synopsis <text>) + (modules <ordered_set_lang>) + (libraries <ocaml_libraries>) + (flags <coq_flags>)) + +This stanza will build all `.v` files in the given directory, wrapping +the library under ``<module_prefix>``. If you declare a +``<package.lib_name>`` a ``.install`` file for the library will be +generated; the optional ``<modules>`` field allows you to filter +the list of modules, and ``<libraries>`` allows to depend on ML +plugins. For the moment, Dune relies on Coq's standard mechanisms +(such as ``COQPATH``) to locate installed Coq libraries. + +By default Dune will skip ``.v`` files present in subdirectories. In +order to enable the usual recursive organization of Coq projects add + +.. code:: scheme + + (include_subdirs qualified) + +to you ``dune`` file. + +Once your project is set up, `dune build` will generate the +`pkg.install` files and all the files necessary for the installation +of your project. + +.. example:: + + A typical stanza for a Coq plugin is split into two parts. An OCaml build directive, which is standard Dune: + + .. code:: scheme + + (library + (name equations_plugin) + (public_name equations.plugin) + (flags :standard -warn-error -3-9-27-32-33-50) + (libraries coq.plugins.cc coq.plugins.extraction)) + + (rule + (targets g_equations.ml) + (deps (:pp-file g_equations.mlg)) + (action (run coqpp %{pp-file}))) + + And a Coq-specific part that depends on it via the ``libraries`` field: + + .. code:: scheme + + (coqlib + (name Equations) ; -R flag + (public_name equations.Equations) + (synopsis "Equations Plugin") + (libraries coq.plugins.extraction equations.plugin) + (modules :standard \ IdDec NoCycle)) ; exclude some modules that don't build + + (include_subdirs qualified) + +.. _coqdep: + +Computing Module dependencies +----------------------------- + +In order to compute module dependencies (to be used by ``make`` or +``dune``), |Coq| provides the ``coqdep`` tool. + +``coqdep`` computes inter-module dependencies for |Coq| and |OCaml| +programs, and prints the dependencies on the standard output in a +format readable by make. When a directory is given as argument, it is +recursively looked at. + +Dependencies of |Coq| modules are computed by looking at ``Require`` +commands (``Require``, ``Require Export``, ``Require Import``), but also at the +command ``Declare ML Module``. + +Dependencies of |OCaml| modules are computed by looking at +`open` commands and the dot notation *module.value*. However, this is +done approximately and you are advised to use ``ocamldep`` instead for the +|OCaml| module dependencies. + +See the man page of ``coqdep`` for more details and options. + +Both Dune and ``coq_makefile`` use ``coqdep`` to compute the +dependencies among the files part of a Coq project. + +.. _coqdoc: + +Documenting |Coq| files with coqdoc +----------------------------------- + +coqdoc is a documentation tool for the proof assistant |Coq|, similar to +``javadoc`` or ``ocamldoc``. The task of coqdoc is + + +#. to produce a nice |Latex| and/or HTML document from |Coq| source files, + readable for a human and not only for the proof assistant; +#. to help the user navigate his own (or third-party) sources. + + + +Principles +~~~~~~~~~~ + +Documentation is inserted into |Coq| files as *special comments*. Thus +your files will compile as usual, whether you use coqdoc or not. coqdoc +presupposes that the given |Coq| files are well-formed (at least +lexically). Documentation starts with ``(**``, followed by a space, and +ends with ``*)``. The documentation format is inspired by Todd +A. Coram’s *Almost Free Text (AFT)* tool: it is mainly ``ASCII`` text with +some syntax-light controls, described below. coqdoc is robust: it +shouldn’t fail, whatever the input is. But remember: “garbage in, +garbage out”. + + +|Coq| material inside documentation. +++++++++++++++++++++++++++++++++++++ + +|Coq| material is quoted between the delimiters ``[`` and ``]``. Square brackets +may be nested, the inner ones being understood as being part of the +quoted code (thus you can quote a term like ``fun x => u`` by writing ``[fun +x => u]``). Inside quotations, the code is pretty-printed in the same +way as it is in code parts. + +Preformatted vernacular is enclosed by ``[[`` and ``]]``. The former must be +followed by a newline and the latter must follow a newline. + + +Pretty-printing. +++++++++++++++++ + +coqdoc uses different faces for identifiers and keywords. The pretty- +printing of |Coq| tokens (identifiers or symbols) can be controlled +using one of the following commands: + +:: + + + (** printing *token* %...LATEX...% #...html...# *) + + +or + +:: + + + (** printing *token* $...LATEX math...$ #...html...# *) + + +It gives the |Latex| and HTML texts to be produced for the given |Coq| +token. Either the |Latex| or the HTML rule may be omitted, causing the +default pretty-printing to be used for this token. + +The printing for one token can be removed with + +:: + + + (** remove printing *token* *) + + +Initially, the pretty-printing table contains the following mapping: + +===== === ==== ===== === ==== ==== === +`->` → `<-` ← `*` × +`<=` ≤ `>=` ≥ `=>` ⇒ +`<>` ≠ `<->` ↔ `|-` ⊢ +`\\/` ∨ `/\\` ∧ `~` ¬ +===== === ==== ===== === ==== ==== === + +Any of these can be overwritten or suppressed using the printing +commands. + +.. note:: + + The recognition of tokens is done by a (``ocaml``) lex + automaton and thus applies the longest-match rule. For instance, `->~` + is recognized as a single token, where |Coq| sees two tokens. It is the + responsibility of the user to insert space between tokens *or* to give + pretty-printing rules for the possible combinations, e.g. + + :: + + (** printing ->~ %\ensuremath{\rightarrow\lnot}% *) + + + +Sections +++++++++ + +Sections are introduced by 1 to 4 asterisks at the beginning of a line +followed by a space and the title of the section. One asterisk is a section, +two a subsection, etc. + +.. example:: + + :: + + (** * Well-founded relations + + In this section, we introduce... *) + + +Lists. +++++++ + +List items are introduced by a leading dash. coqdoc uses whitespace to +determine the depth of a new list item and which text belongs in which +list items. A list ends when a line of text starts at or before the +level of indenting of the list’s dash. A list item’s dash must always +be the first non-space character on its line (so, in particular, a +list can not begin on the first line of a comment - start it on the +second line instead). + +.. example:: + + :: + + We go by induction on [n]: + - If [n] is 0... + - If [n] is [S n'] we require... + + two paragraphs of reasoning, and two subcases: + + - In the first case... + - In the second case... + + So the theorem holds. + + + +Rules. +++++++ + +More than 4 leading dashes produce a horizontal rule. + + +Emphasis. ++++++++++ + +Text can be italicized by enclosing it in underscores. A non-identifier +character must precede the leading underscore and follow the trailing +underscore, so that uses of underscores in names aren’t mistaken for +emphasis. Usually, these are spaces or punctuation. + +:: + + This sentence contains some _emphasized text_. + + + +Escaping to |Latex| and HTML. ++++++++++++++++++++++++++++++++ + +Pure |Latex| or HTML material can be inserted using the following +escape sequences: + + ++ ``$...LATEX stuff...$`` inserts some |Latex| material in math mode. + Simply discarded in HTML output. ++ ``%...LATEX stuff...%`` inserts some |Latex| material. Simply + discarded in HTML output. ++ ``#...HTML stuff...#`` inserts some HTML material. Simply discarded in + |Latex| output. + +.. note:: + to simply output the characters ``$``, ``%`` and ``#`` and escaping + their escaping role, these characters must be doubled. + + +Verbatim +++++++++ + +Verbatim material is introduced by a leading ``<<`` and closed by ``>>`` +at the beginning of a line. + +.. example:: + + :: + + Here is the corresponding caml code: + << + let rec fact n = + if n <= 1 then 1 else n * fact (n-1) + >> + + + +Hyperlinks +++++++++++ + +Hyperlinks can be inserted into the HTML output, so that any +identifier is linked to the place of its definition. + +``coqc file.v`` automatically dumps localization information in +``file.glob`` or appends it to a file specified using the option ``--dump-glob +file``. Take care of erasing this global file, if any, when starting +the whole compilation process. + +Then invoke coqdoc or ``coqdoc --glob-from file`` to tell coqdoc to look +for name resolutions in the file ``file`` (it will look in ``file.glob`` +by default). + +Identifiers from the |Coq| standard library are linked to the Coq website +`<http://coq.inria.fr/library/>`_. This behavior can be changed +using command line options ``--no-externals`` and ``--coqlib``; see below. + + +Hiding / Showing parts of the source. ++++++++++++++++++++++++++++++++++++++ + +Some parts of the source can be hidden using command line options ``-g`` +and ``-l`` (see below), or using such comments: + +:: + + + (* begin hide *) + *some Coq material* + (* end hide *) + + +Conversely, some parts of the source which would be hidden can be +shown using such comments: + +:: + + + (* begin show *) + *some Coq material* + (* end show *) + + +The latter cannot be used around some inner parts of a proof, but can +be used around a whole proof. + + +Usage +~~~~~ + +coqdoc is invoked on a shell command line as follows: +``coqdoc <options and files>``. +Any command line argument which is not an option is considered to be a +file (even if it starts with a ``-``). |Coq| files are identified by the +suffixes ``.v`` and ``.g`` and |Latex| files by the suffix ``.tex``. + + +:HTML output: This is the default output format. One HTML file is created for + each |Coq| file given on the command line, together with a file + ``index.html`` (unless ``option-no-index is passed``). The HTML pages use a + style sheet named ``style.css``. Such a file is distributed with coqdoc. +:|Latex| output: A single |Latex| file is created, on standard + output. It can be redirected to a file using the option ``-o``. The order of + files on the command line is kept in the final document. |Latex| + files given on the command line are copied ‘as is’ in the final + document . DVI and PostScript can be produced directly with the + options ``-dvi`` and ``-ps`` respectively. +:TEXmacs output: To translate the input files to TEXmacs format, + to be used by the TEXmacs |Coq| interface. + + + +Command line options +++++++++++++++++++++ + + +**Overall options** + + + :--HTML: Select a HTML output. + :--|Latex|: Select a |Latex| output. + :--dvi: Select a DVI output. + :--ps: Select a PostScript output. + :--texmacs: Select a TEXmacs output. + :--stdout: Write output to stdout. + :-o file, --output file: Redirect the output into the file ‘file’ + (meaningless with ``-html``). + :-d dir, --directory dir: Output files into directory ‘dir’ instead of + the current directory (option ``-d`` does not change the filename specified + with the option ``-o``, if any). + :--body-only: Suppress the header and trailer of the final document. + Thus, you can insert the resulting document into a larger one. + :-p string, --preamble string: Insert some material in the |Latex| + preamble, right before ``\begin{document}`` (meaningless with ``-html``). + :--vernac-file file,--tex-file file: Considers the file ‘file’ + respectively as a ``.v`` (or ``.g``) file or a ``.tex`` file. + :--files-from file: Read filenames to be processed from the file ‘file’ as if + they were given on the command line. Useful for program sources split + up into several directories. + :-q, --quiet: Be quiet. Do not print anything except errors. + :-h, --help: Give a short summary of the options and exit. + :-v, --version: Print the version and exit. + + + +**Index options** + + The default behavior is to build an index, for the HTML output only, + into ``index.html``. + + :--no-index: Do not output the index. + :--multi-index: Generate one page for each category and each letter in + the index, together with a top page ``index.html``. + :--index string: Make the filename of the index string instead of + “index”. Useful since “index.html” is special. + + + +**Table of contents option** + + :-toc, --table-of-contents: Insert a table of contents. For a |Latex| + output, it inserts a ``\tableofcontents`` at the beginning of the + document. For a HTML output, it builds a table of contents into + ``toc.html``. + :--toc-depth int: Only include headers up to depth ``int`` in the table of + contents. + + +**Hyperlink options** + + :--glob-from file: Make references using |Coq| globalizations from file + file. (Such globalizations are obtained with Coq option ``-dump-glob``). + :--no-externals: Do not insert links to the |Coq| standard library. + :--external url coqdir: Use given URL for linking references whose + name starts with prefix ``coqdir``. + :--coqlib url: Set base URL for the Coq standard library (default is + `<http://coq.inria.fr/library/>`_). This is equivalent to ``--external url + Coq``. + :-R dir coqdir: Map physical directory dir to |Coq| logical + directory ``coqdir`` (similarly to |Coq| option ``-R``). + + .. note:: + + option ``-R`` only has + effect on the files *following* it on the command line, so you will + probably need to put this option first. + + +**Title options** + + :-s , --short: Do not insert titles for the files. The default + behavior is to insert a title like “Library Foo” for each file. + :--lib-name string: Print “string Foo” instead of “Library Foo” in + titles. For example “Chapter” and “Module” are reasonable choices. + :--no-lib-name: Print just “Foo” instead of “Library Foo” in titles. + :--lib-subtitles: Look for library subtitles. When enabled, the + beginning of each file is checked for a comment of the form: + + :: + + (** * ModuleName : text *) + + where ``ModuleName`` must be the name of the file. If it is present, the + text is used as a subtitle for the module in appropriate places. + :-t string, --title string: Set the document title. + + +**Contents options** + + :-g, --gallina: Do not print proofs. + :-l, --light: Light mode. Suppress proofs (as with ``-g``) and the following commands: + + + [Recursive] Tactic Definition + + Hint / Hints + + Require + + Transparent / Opaque + + Implicit Argument / Implicits + + Section / Variable / Hypothesis / End + + + + The behavior of options ``-g`` and ``-l`` can be locally overridden using the + ``(* begin show *) … (* end show *)`` environment (see above). + + There are a few options that control the parsing of comments: + + :--parse-comments: Parse regular comments delimited by ``(*`` and ``*)`` as + well. They are typeset inline. + :--plain-comments: Do not interpret comments, simply copy them as + plain-text. + :--interpolate: Use the globalization information to typeset + identifiers appearing in |Coq| escapings inside comments. + +**Language options** + + + The default behavior is to assume ASCII 7 bit input files. + + :-latin1, --latin1: Select ISO-8859-1 input files. It is equivalent to + --inputenc latin1 --charset iso-8859-1. + :-utf8, --utf8: Set --inputenc utf8x for |Latex| output and--charset + utf-8 for HTML output. Also use Unicode replacements for a couple of + standard plain ASCII notations such as → for ``->`` and ∀ for ``forall``. |Latex| + UTF-8 support can be found + at `<http://www.ctan.org/pkg/unicode>`_. For the interpretation of Unicode + characters by |Latex|, extra packages which coqdoc does not provide + by default might be required, such as textgreek for some Greek letters + or ``stmaryrd`` for some mathematical symbols. If a Unicode character is + missing an interpretation in the utf8x input encoding, add + ``\DeclareUnicodeCharacter{code}{LATEX-interpretation}``. Packages + and declarations can be added with option ``-p``. + :--inputenc string: Give a |Latex| input encoding, as an option to |Latex| + package ``inputenc``. + :--charset string: Specify the HTML character set, to be inserted in + the HTML header. + + + +The coqdoc |Latex| style file +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +In case you choose to produce a document without the default |Latex| +preamble (by using option ``--no-preamble``), then you must insert into +your own preamble the command + +:: + + \usepackage{coqdoc} + +The package optionally takes the argument ``[color]`` to typeset +identifiers with colors (this requires the ``xcolor`` package). + +Then you may alter the rendering of the document by redefining some +macros: + +:coqdockw, coqdocid, …: The one-argument macros for typesetting + keywords and identifiers. Defaults are sans-serif for keywords and + italic for identifiers.For example, if you would like a slanted font + for keywords, you may insert + + :: + + \renewcommand{\coqdockw}[1]{\textsl{#1}} + + + anywhere between ``\usepackage{coqdoc}`` and ``\begin{document}``. + + +:coqdocmodule: + One-argument macro for typesetting the title of a ``.v`` + file. Default is + + :: + + \newcommand{\coqdocmodule}[1]{\section*{Module #1}} + + and you may redefine it using ``\renewcommand``. + +Embedded Coq phrases inside |Latex| documents +--------------------------------------------- + +When writing documentation about a proof development, one may want +to insert |Coq| phrases inside a |Latex| document, possibly together +with the corresponding answers of the system. We provide a mechanical +way to process such |Coq| phrases embedded in |Latex| files: the ``coq-tex`` +filter. This filter extracts |Coq| phrases embedded in |Latex| files, +evaluates them, and insert the outcome of the evaluation after each +phrase. + +Starting with a file ``file.tex`` containing |Coq| phrases, the ``coq-tex`` +filter produces a file named ``file.v.tex`` with the Coq outcome. + +There are options to produce the |Coq| parts in smaller font, italic, +between horizontal rules, etc. See the man page of ``coq-tex`` for more +details. + + +Man pages +--------- + +There are man pages for the commands ``coqdep`` and ``coq-tex``. Man +pages are installed at installation time (see installation +instructions in file ``INSTALL``, step 6). diff --git a/doc/sphinx/proof-engine/detailed-tactic-examples.rst b/doc/sphinx/proof-engine/detailed-tactic-examples.rst new file mode 100644 index 0000000000..b629d15b11 --- /dev/null +++ b/doc/sphinx/proof-engine/detailed-tactic-examples.rst @@ -0,0 +1,776 @@ +.. _detailedexamplesoftactics: + +Detailed examples of tactics +============================ + +This chapter presents detailed examples of certain tactics, to +illustrate their behavior. + +.. _dependent-induction: + +dependent induction +------------------- + +The tactics ``dependent induction`` and ``dependent destruction`` are another +solution for inverting inductive predicate instances and potentially +doing induction at the same time. It is based on the ``BasicElim`` tactic +of Conor McBride which works by abstracting each argument of an +inductive instance by a variable and constraining it by equalities +afterwards. This way, the usual induction and destruct tactics can be +applied to the abstracted instance and after simplification of the +equalities we get the expected goals. + +The abstracting tactic is called generalize_eqs and it takes as +argument a hypothesis to generalize. It uses the JMeq datatype +defined in Coq.Logic.JMeq, hence we need to require it before. For +example, revisiting the first example of the inversion documentation: + +.. coqtop:: in reset + + Require Import Coq.Logic.JMeq. + + Inductive Le : nat -> nat -> Set := + | LeO : forall n:nat, Le 0 n + | LeS : forall n m:nat, Le n m -> Le (S n) (S m). + + Parameter P : nat -> nat -> Prop. + + Goal forall n m:nat, Le (S n) m -> P n m. + + intros n m H. + +.. coqtop:: all + + generalize_eqs H. + +The index ``S n`` gets abstracted by a variable here, but a corresponding +equality is added under the abstract instance so that no information +is actually lost. The goal is now almost amenable to do induction or +case analysis. One should indeed first move ``n`` into the goal to +strengthen it before doing induction, or ``n`` will be fixed in the +inductive hypotheses (this does not matter for case analysis). As a +rule of thumb, all the variables that appear inside constructors in +the indices of the hypothesis should be generalized. This is exactly +what the ``generalize_eqs_vars`` variant does: + +.. coqtop:: all abort + + generalize_eqs_vars H. + induction H. + +As the hypothesis itself did not appear in the goal, we did not need +to use an heterogeneous equality to relate the new hypothesis to the +old one (which just disappeared here). However, the tactic works just +as well in this case, e.g.: + +.. coqtop:: none + + Require Import Coq.Program.Equality. + +.. coqtop:: in + + Parameter Q : forall (n m : nat), Le n m -> Prop. + Goal forall n m (p : Le (S n) m), Q (S n) m p. + +.. coqtop:: all + + intros n m p. + generalize_eqs_vars p. + +One drawback of this approach is that in the branches one will have to +substitute the equalities back into the instance to get the right +assumptions. Sometimes injection of constructors will also be needed +to recover the needed equalities. Also, some subgoals should be +directly solved because of inconsistent contexts arising from the +constraints on indexes. The nice thing is that we can make a tactic +based on discriminate, injection and variants of substitution to +automatically do such simplifications (which may involve the axiom K). +This is what the ``simplify_dep_elim`` tactic from ``Coq.Program.Equality`` +does. For example, we might simplify the previous goals considerably: + +.. coqtop:: all abort + + induction p ; simplify_dep_elim. + +The higher-order tactic ``do_depind`` defined in ``Coq.Program.Equality`` +takes a tactic and combines the building blocks we have seen with it: +generalizing by equalities calling the given tactic with the +generalized induction hypothesis as argument and cleaning the subgoals +with respect to equalities. Its most important instantiations +are ``dependent induction`` and ``dependent destruction`` that do induction or +simply case analysis on the generalized hypothesis. For example we can +redo what we’ve done manually with dependent destruction: + +.. coqtop:: in + + Lemma ex : forall n m:nat, Le (S n) m -> P n m. + +.. coqtop:: in + + intros n m H. + +.. coqtop:: all abort + + dependent destruction H. + +This gives essentially the same result as inversion. Now if the +destructed hypothesis actually appeared in the goal, the tactic would +still be able to invert it, contrary to dependent inversion. Consider +the following example on vectors: + +.. coqtop:: in + + Set Implicit Arguments. + +.. coqtop:: in + + Parameter A : Set. + +.. coqtop:: in + + Inductive vector : nat -> Type := + | vnil : vector 0 + | vcons : A -> forall n, vector n -> vector (S n). + +.. coqtop:: in + + Goal forall n, forall v : vector (S n), + exists v' : vector n, exists a : A, v = vcons a v'. + +.. coqtop:: in + + intros n v. + +.. coqtop:: all + + dependent destruction v. + +In this case, the ``v`` variable can be replaced in the goal by the +generalized hypothesis only when it has a type of the form ``vector (S n)``, +that is only in the second case of the destruct. The first one is +dismissed because ``S n <> 0``. + + +A larger example +~~~~~~~~~~~~~~~~ + +Let’s see how the technique works with induction on inductive +predicates on a real example. We will develop an example application +to the theory of simply-typed lambda-calculus formalized in a +dependently-typed style: + +.. coqtop:: in reset + + Inductive type : Type := + | base : type + | arrow : type -> type -> type. + +.. coqtop:: in + + Notation " t --> t' " := (arrow t t') (at level 20, t' at next level). + +.. coqtop:: in + + Inductive ctx : Type := + | empty : ctx + | snoc : ctx -> type -> ctx. + +.. coqtop:: in + + Notation " G , tau " := (snoc G tau) (at level 20, tau at next level). + +.. coqtop:: in + + Fixpoint conc (G D : ctx) : ctx := + match D with + | empty => G + | snoc D' x => snoc (conc G D') x + end. + +.. coqtop:: in + + Notation " G ; D " := (conc G D) (at level 20). + +.. coqtop:: in + + Inductive term : ctx -> type -> Type := + | ax : forall G tau, term (G, tau) tau + | weak : forall G tau, + term G tau -> forall tau', term (G, tau') tau + | abs : forall G tau tau', + term (G , tau) tau' -> term G (tau --> tau') + | app : forall G tau tau', + term G (tau --> tau') -> term G tau -> term G tau'. + +We have defined types and contexts which are snoc-lists of types. We +also have a ``conc`` operation that concatenates two contexts. The ``term`` +datatype represents in fact the possible typing derivations of the +calculus, which are isomorphic to the well-typed terms, hence the +name. A term is either an application of: + + ++ the axiom rule to type a reference to the first variable in a + context ++ the weakening rule to type an object in a larger context ++ the abstraction or lambda rule to type a function ++ the application to type an application of a function to an argument + + +Once we have this datatype we want to do proofs on it, like weakening: + +.. coqtop:: in abort + + Lemma weakening : forall G D tau, term (G ; D) tau -> + forall tau', term (G , tau' ; D) tau. + +The problem here is that we can’t just use induction on the typing +derivation because it will forget about the ``G ; D`` constraint appearing +in the instance. A solution would be to rewrite the goal as: + +.. coqtop:: in abort + + Lemma weakening' : forall G' tau, term G' tau -> + forall G D, (G ; D) = G' -> + forall tau', term (G, tau' ; D) tau. + +With this proper separation of the index from the instance and the +right induction loading (putting ``G`` and ``D`` after the inducted-on +hypothesis), the proof will go through, but it is a very tedious +process. One is also forced to make a wrapper lemma to get back the +more natural statement. The ``dependent induction`` tactic alleviates this +trouble by doing all of this plumbing of generalizing and substituting +back automatically. Indeed we can simply write: + +.. coqtop:: in + + Require Import Coq.Program.Tactics. + Require Import Coq.Program.Equality. + +.. coqtop:: in + + Lemma weakening : forall G D tau, term (G ; D) tau -> + forall tau', term (G , tau' ; D) tau. + +.. coqtop:: in + + Proof with simpl in * ; simpl_depind ; auto. + +.. coqtop:: in + + intros G D tau H. dependent induction H generalizing G D ; intros. + +This call to dependent induction has an additional arguments which is +a list of variables appearing in the instance that should be +generalized in the goal, so that they can vary in the induction +hypotheses. By default, all variables appearing inside constructors +(except in a parameter position) of the instantiated hypothesis will +be generalized automatically but one can always give the list +explicitly. + +.. coqtop:: all + + Show. + +The ``simpl_depind`` tactic includes an automatic tactic that tries to +simplify equalities appearing at the beginning of induction +hypotheses, generally using trivial applications of ``reflexivity``. In +cases where the equality is not between constructor forms though, one +must help the automation by giving some arguments, using the +``specialize`` tactic for example. + +.. coqtop:: in + + destruct D... apply weak; apply ax. apply ax. + +.. coqtop:: in + + destruct D... + +.. coqtop:: all + + Show. + +.. coqtop:: all + + specialize (IHterm G0 empty eq_refl). + +Once the induction hypothesis has been narrowed to the right equality, +it can be used directly. + +.. coqtop:: all + + apply weak, IHterm. + +Now concluding this subgoal is easy. + +.. coqtop:: in + + constructor; apply IHterm; reflexivity. + +.. seealso:: + The :tacn:`induction`, :tacn:`case`, and :tacn:`inversion` tactics. + + +autorewrite +----------- + +Here are two examples of ``autorewrite`` use. The first one ( *Ackermann +function*) shows actually a quite basic use where there is no +conditional rewriting. The second one ( *Mac Carthy function*) +involves conditional rewritings and shows how to deal with them using +the optional tactic of the ``Hint Rewrite`` command. + + +.. example:: Ackermann function + + .. coqtop:: in reset + + Require Import Arith. + + .. coqtop:: in + + Parameter Ack : nat -> nat -> nat. + + .. coqtop:: in + + Axiom Ack0 : forall m:nat, Ack 0 m = S m. + Axiom Ack1 : forall n:nat, Ack (S n) 0 = Ack n 1. + Axiom Ack2 : forall n m:nat, Ack (S n) (S m) = Ack n (Ack (S n) m). + + .. coqtop:: in + + Hint Rewrite Ack0 Ack1 Ack2 : base0. + + .. coqtop:: all + + Lemma ResAck0 : Ack 3 2 = 29. + + .. coqtop:: all + + autorewrite with base0 using try reflexivity. + +.. example:: MacCarthy function + + .. coqtop:: in reset + + Require Import Omega. + + .. coqtop:: in + + Parameter g : nat -> nat -> nat. + + .. coqtop:: in + + Axiom g0 : forall m:nat, g 0 m = m. + Axiom g1 : forall n m:nat, (n > 0) -> (m > 100) -> g n m = g (pred n) (m - 10). + Axiom g2 : forall n m:nat, (n > 0) -> (m <= 100) -> g n m = g (S n) (m + 11). + + .. coqtop:: in + + Hint Rewrite g0 g1 g2 using omega : base1. + + .. coqtop:: in + + Lemma Resg0 : g 1 110 = 100. + + .. coqtop:: out + + Show. + + .. coqtop:: all + + autorewrite with base1 using reflexivity || simpl. + + .. coqtop:: none + + Qed. + + .. coqtop:: all + + Lemma Resg1 : g 1 95 = 91. + + .. coqtop:: all + + autorewrite with base1 using reflexivity || simpl. + + .. coqtop:: none + + Qed. + +Using the tactic language +------------------------- + + +About the cardinality of the set of natural numbers +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +The first example which shows how to use pattern matching over the +proof context is a proof of the fact that natural numbers have more +than two elements. This can be done as follows: + +.. coqtop:: in reset + + Lemma card_nat : + ~ exists x : nat, exists y : nat, forall z:nat, x = z \/ y = z. + Proof. + +.. coqtop:: in + + red; intros (x, (y, Hy)). + +.. coqtop:: in + + elim (Hy 0); elim (Hy 1); elim (Hy 2); intros; + + match goal with + | _ : ?a = ?b, _ : ?a = ?c |- _ => + cut (b = c); [ discriminate | transitivity a; auto ] + end. + +.. coqtop:: in + + Qed. + +We can notice that all the (very similar) cases coming from the three +eliminations (with three distinct natural numbers) are successfully +solved by a match goal structure and, in particular, with only one +pattern (use of non-linear matching). + + +Permutations of lists +~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +A more complex example is the problem of permutations of +lists. The aim is to show that a list is a permutation of +another list. + +.. coqtop:: in reset + + Section Sort. + +.. coqtop:: in + + Variable A : Set. + +.. coqtop:: in + + Inductive perm : list A -> list A -> Prop := + | perm_refl : forall l, perm l l + | perm_cons : forall a l0 l1, perm l0 l1 -> perm (a :: l0) (a :: l1) + | perm_append : forall a l, perm (a :: l) (l ++ a :: nil) + | perm_trans : forall l0 l1 l2, perm l0 l1 -> perm l1 l2 -> perm l0 l2. + +.. coqtop:: in + + End Sort. + +First, we define the permutation predicate as shown above. + +.. coqtop:: none + + Require Import List. + + +.. coqtop:: in + + Ltac perm_aux n := + match goal with + | |- (perm _ ?l ?l) => apply perm_refl + | |- (perm _ (?a :: ?l1) (?a :: ?l2)) => + let newn := eval compute in (length l1) in + (apply perm_cons; perm_aux newn) + | |- (perm ?A (?a :: ?l1) ?l2) => + match eval compute in n with + | 1 => fail + | _ => + let l1' := constr:(l1 ++ a :: nil) in + (apply (perm_trans A (a :: l1) l1' l2); + [ apply perm_append | compute; perm_aux (pred n) ]) + end + end. + +Next we define an auxiliary tactic ``perm_aux`` which takes an argument +used to control the recursion depth. This tactic behaves as follows. If +the lists are identical (i.e. convertible), it concludes. Otherwise, if +the lists have identical heads, it proceeds to look at their tails. +Finally, if the lists have different heads, it rotates the first list by +putting its head at the end if the new head hasn't been the head previously. To check this, we keep track of the +number of performed rotations using the argument ``n``. We do this by +decrementing ``n`` each time we perform a rotation. It works because +for a list of length ``n`` we can make exactly ``n - 1`` rotations +to generate at most ``n`` distinct lists. Notice that we use the natural +numbers of Coq for the rotation counter. From :ref:`ltac-syntax` we know +that it is possible to use the usual natural numbers, but they are only +used as arguments for primitive tactics and they cannot be handled, so, +in particular, we cannot make computations with them. Thus the natural +choice is to use Coq data structures so that Coq makes the computations +(reductions) by ``eval compute in`` and we can get the terms back by match. + +.. coqtop:: in + + Ltac solve_perm := + match goal with + | |- (perm _ ?l1 ?l2) => + match eval compute in (length l1 = length l2) with + | (?n = ?n) => perm_aux n + end + end. + +The main tactic is ``solve_perm``. It computes the lengths of the two lists +and uses them as arguments to call ``perm_aux`` if the lengths are equal (if they +aren't, the lists cannot be permutations of each other). Using this tactic we +can now prove lemmas as follows: + +.. coqtop:: in + + Lemma solve_perm_ex1 : + perm nat (1 :: 2 :: 3 :: nil) (3 :: 2 :: 1 :: nil). + Proof. solve_perm. Qed. + +.. coqtop:: in + + Lemma solve_perm_ex2 : + perm nat + (0 :: 1 :: 2 :: 3 :: 4 :: 5 :: 6 :: 7 :: 8 :: 9 :: nil) + (0 :: 2 :: 4 :: 6 :: 8 :: 9 :: 7 :: 5 :: 3 :: 1 :: nil). + Proof. solve_perm. Qed. + +Deciding intuitionistic propositional logic +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Pattern matching on goals allows a powerful backtracking when returning tactic +values. An interesting application is the problem of deciding intuitionistic +propositional logic. Considering the contraction-free sequent calculi LJT* of +Roy Dyckhoff :cite:`Dyc92`, it is quite natural to code such a tactic using the +tactic language as shown below. + +.. coqtop:: in reset + + Ltac basic := + match goal with + | |- True => trivial + | _ : False |- _ => contradiction + | _ : ?A |- ?A => assumption + end. + +.. coqtop:: in + + Ltac simplify := + repeat (intros; + match goal with + | H : ~ _ |- _ => red in H + | H : _ /\ _ |- _ => + elim H; do 2 intro; clear H + | H : _ \/ _ |- _ => + elim H; intro; clear H + | H : ?A /\ ?B -> ?C |- _ => + cut (A -> B -> C); + [ intro | intros; apply H; split; assumption ] + | H: ?A \/ ?B -> ?C |- _ => + cut (B -> C); + [ cut (A -> C); + [ intros; clear H + | intro; apply H; left; assumption ] + | intro; apply H; right; assumption ] + | H0 : ?A -> ?B, H1 : ?A |- _ => + cut B; [ intro; clear H0 | apply H0; assumption ] + | |- _ /\ _ => split + | |- ~ _ => red + end). + +.. coqtop:: in + + Ltac my_tauto := + simplify; basic || + match goal with + | H : (?A -> ?B) -> ?C |- _ => + cut (B -> C); + [ intro; cut (A -> B); + [ intro; cut C; + [ intro; clear H | apply H; assumption ] + | clear H ] + | intro; apply H; intro; assumption ]; my_tauto + | H : ~ ?A -> ?B |- _ => + cut (False -> B); + [ intro; cut (A -> False); + [ intro; cut B; + [ intro; clear H | apply H; assumption ] + | clear H ] + | intro; apply H; red; intro; assumption ]; my_tauto + | |- _ \/ _ => (left; my_tauto) || (right; my_tauto) + end. + +The tactic ``basic`` tries to reason using simple rules involving truth, falsity +and available assumptions. The tactic ``simplify`` applies all the reversible +rules of Dyckhoff’s system. Finally, the tactic ``my_tauto`` (the main +tactic to be called) simplifies with ``simplify``, tries to conclude with +``basic`` and tries several paths using the backtracking rules (one of the +four Dyckhoff’s rules for the left implication to get rid of the contraction +and the right ``or``). + +Having defined ``my_tauto``, we can prove tautologies like these: + +.. coqtop:: in + + Lemma my_tauto_ex1 : + forall A B : Prop, A /\ B -> A \/ B. + Proof. my_tauto. Qed. + +.. coqtop:: in + + Lemma my_tauto_ex2 : + forall A B : Prop, (~ ~ B -> B) -> (A -> B) -> ~ ~ A -> B. + Proof. my_tauto. Qed. + + +Deciding type isomorphisms +~~~~~~~~~~~~~~~~~~~~~~~~~~ + +A more tricky problem is to decide equalities between types modulo +isomorphisms. Here, we choose to use the isomorphisms of the simply +typed λ-calculus with Cartesian product and unit type (see, for +example, :cite:`RC95`). The axioms of this λ-calculus are given below. + +.. coqtop:: in reset + + Open Scope type_scope. + +.. coqtop:: in + + Section Iso_axioms. + +.. coqtop:: in + + Variables A B C : Set. + +.. coqtop:: in + + Axiom Com : A * B = B * A. + + Axiom Ass : A * (B * C) = A * B * C. + + Axiom Cur : (A * B -> C) = (A -> B -> C). + + Axiom Dis : (A -> B * C) = (A -> B) * (A -> C). + + Axiom P_unit : A * unit = A. + + Axiom AR_unit : (A -> unit) = unit. + + Axiom AL_unit : (unit -> A) = A. + +.. coqtop:: in + + Lemma Cons : B = C -> A * B = A * C. + + Proof. + + intro Heq; rewrite Heq; reflexivity. + + Qed. + +.. coqtop:: in + + End Iso_axioms. + +.. coqtop:: in + + Ltac simplify_type ty := + match ty with + | ?A * ?B * ?C => + rewrite <- (Ass A B C); try simplify_type_eq + | ?A * ?B -> ?C => + rewrite (Cur A B C); try simplify_type_eq + | ?A -> ?B * ?C => + rewrite (Dis A B C); try simplify_type_eq + | ?A * unit => + rewrite (P_unit A); try simplify_type_eq + | unit * ?B => + rewrite (Com unit B); try simplify_type_eq + | ?A -> unit => + rewrite (AR_unit A); try simplify_type_eq + | unit -> ?B => + rewrite (AL_unit B); try simplify_type_eq + | ?A * ?B => + (simplify_type A; try simplify_type_eq) || + (simplify_type B; try simplify_type_eq) + | ?A -> ?B => + (simplify_type A; try simplify_type_eq) || + (simplify_type B; try simplify_type_eq) + end + with simplify_type_eq := + match goal with + | |- ?A = ?B => try simplify_type A; try simplify_type B + end. + +.. coqtop:: in + + Ltac len trm := + match trm with + | _ * ?B => let succ := len B in constr:(S succ) + | _ => constr:(1) + end. + +.. coqtop:: in + + Ltac assoc := repeat rewrite <- Ass. + +.. coqtop:: in + + Ltac solve_type_eq n := + match goal with + | |- ?A = ?A => reflexivity + | |- ?A * ?B = ?A * ?C => + apply Cons; let newn := len B in solve_type_eq newn + | |- ?A * ?B = ?C => + match eval compute in n with + | 1 => fail + | _ => + pattern (A * B) at 1; rewrite Com; assoc; solve_type_eq (pred n) + end + end. + +.. coqtop:: in + + Ltac compare_structure := + match goal with + | |- ?A = ?B => + let l1 := len A + with l2 := len B in + match eval compute in (l1 = l2) with + | ?n = ?n => solve_type_eq n + end + end. + +.. coqtop:: in + + Ltac solve_iso := simplify_type_eq; compare_structure. + +The tactic to judge equalities modulo this axiomatization is shown above. +The algorithm is quite simple. First types are simplified using axioms that +can be oriented (this is done by ``simplify_type`` and ``simplify_type_eq``). +The normal forms are sequences of Cartesian products without Cartesian product +in the left component. These normal forms are then compared modulo permutation +of the components by the tactic ``compare_structure``. If they have the same +lengths, the tactic ``solve_type_eq`` attempts to prove that the types are equal. +The main tactic that puts all these components together is called ``solve_iso``. + +Here are examples of what can be solved by ``solve_iso``. + +.. coqtop:: in + + Lemma solve_iso_ex1 : + forall A B : Set, A * unit * B = B * (unit * A). + Proof. + intros; solve_iso. + Qed. + +.. coqtop:: in + + Lemma solve_iso_ex2 : + forall A B C : Set, + (A * unit -> B * (C * unit)) = + (A * unit -> (C -> unit) * C) * (unit -> A -> B). + Proof. + intros; solve_iso. + Qed. diff --git a/doc/sphinx/proof-engine/ltac.rst b/doc/sphinx/proof-engine/ltac.rst new file mode 100644 index 0000000000..0322b43694 --- /dev/null +++ b/doc/sphinx/proof-engine/ltac.rst @@ -0,0 +1,1383 @@ +.. _ltac: + +The tactic language +=================== + +This chapter gives a compact documentation of |Ltac|, the tactic language +available in |Coq|. We start by giving the syntax, and next, we present the +informal semantics. If you want to know more regarding this language and +especially about its foundations, you can refer to :cite:`Del00`. Chapter +:ref:`detailedexamplesoftactics` is devoted to giving small but nontrivial +use examples of this language. + +.. _ltac-syntax: + +Syntax +------ + +The syntax of the tactic language is given below. See Chapter +:ref:`gallinaspecificationlanguage` for a description of the BNF metasyntax used +in these grammar rules. Various already defined entries will be used in this +chapter: entries :token:`natural`, :token:`integer`, :token:`ident`, +:token:`qualid`, :token:`term`, :token:`cpattern` and :token:`atomic_tactic` +represent respectively the natural and integer numbers, the authorized +identificators and qualified names, Coq terms and patterns and all the atomic +tactics described in Chapter :ref:`tactics`. The syntax of :token:`cpattern` is +the same as that of terms, but it is extended with pattern matching +metavariables. In :token:`cpattern`, a pattern matching metavariable is +represented with the syntax :g:`?id` where :g:`id` is an :token:`ident`. The +notation :g:`_` can also be used to denote metavariable whose instance is +irrelevant. In the notation :g:`?id`, the identifier allows us to keep +instantiations and to make constraints whereas :g:`_` shows that we are not +interested in what will be matched. On the right hand side of pattern matching +clauses, the named metavariables are used without the question mark prefix. There +is also a special notation for second-order pattern matching problems: in an +applicative pattern of the form :g:`@?id id1 … idn`, the variable id matches any +complex expression with (possible) dependencies in the variables :g:`id1 … idn` +and returns a functional term of the form :g:`fun id1 … idn => term`. + +The main entry of the grammar is :n:`@expr`. This language is used in proof +mode but it can also be used in toplevel definitions as shown below. + +.. note:: + + - The infix tacticals ``… || …`` , ``… + …`` , and ``… ; …`` are associative. + + .. example:: + + If you want that :n:`@tactic__2; @tactic__3` be fully run on the first + subgoal generated by :n:`@tactic__1`, before running on the other + subgoals, then you should not write + :n:`@tactic__1; (@tactic__2; @tactic__3)` but rather + :n:`@tactic__1; [> @tactic__2; @tactic__3 .. ]`. + + - In :token:`tacarg`, there is an overlap between :token:`qualid` as a + direct tactic argument and :token:`qualid` as a particular case of + :token:`term`. The resolution is done by first looking for a reference + of the tactic language and if it fails, for a reference to a term. + To force the resolution as a reference of the tactic language, use the + form :n:`ltac:(@qualid)`. To force the resolution as a reference to a + term, use the syntax :n:`(@qualid)`. + + - As shown by the figure, tactical ``… || …`` binds more than the prefix + tacticals :tacn:`try`, :tacn:`repeat`, :tacn:`do` and :tacn:`abstract` + which themselves bind more than the postfix tactical ``… ;[ … ]`` + which binds at the same level as ``… ; …`` . + + .. example:: + + :n:`try repeat @tactic__1 || @tactic__2; @tactic__3; [ {+| @tactic } ]; @tactic__4` + + is understood as: + + :n:`((try (repeat (@tactic__1 || @tactic__2)); @tactic__3); [ {+| @tactic } ]); @tactic__4` + +.. productionlist:: coq + expr : `expr` ; `expr` + : [> `expr` | ... | `expr` ] + : `expr` ; [ `expr` | ... | `expr` ] + : `tacexpr3` + tacexpr3 : do (`natural` | `ident`) `tacexpr3` + : progress `tacexpr3` + : repeat `tacexpr3` + : try `tacexpr3` + : once `tacexpr3` + : exactly_once `tacexpr3` + : timeout (`natural` | `ident`) `tacexpr3` + : time [`string`] `tacexpr3` + : only `selector`: `tacexpr3` + : `tacexpr2` + tacexpr2 : `tacexpr1` || `tacexpr3` + : `tacexpr1` + `tacexpr3` + : tryif `tacexpr1` then `tacexpr1` else `tacexpr1` + : `tacexpr1` + tacexpr1 : fun `name` ... `name` => `atom` + : let [rec] `let_clause` with ... with `let_clause` in `atom` + : match goal with `context_rule` | ... | `context_rule` end + : match reverse goal with `context_rule` | ... | `context_rule` end + : match `expr` with `match_rule` | ... | `match_rule` end + : lazymatch goal with `context_rule` | ... | `context_rule` end + : lazymatch reverse goal with `context_rule` | ... | `context_rule` end + : lazymatch `expr` with `match_rule` | ... | `match_rule` end + : multimatch goal with `context_rule` | ... | `context_rule` end + : multimatch reverse goal with `context_rule` | ... | `context_rule` end + : multimatch `expr` with `match_rule` | ... | `match_rule` end + : abstract `atom` + : abstract `atom` using `ident` + : first [ `expr` | ... | `expr` ] + : solve [ `expr` | ... | `expr` ] + : idtac [ `message_token` ... `message_token`] + : fail [`natural`] [`message_token` ... `message_token`] + : fresh [ `component` … `component` ] + : context `ident` [`term`] + : eval `redexpr` in `term` + : type of `term` + : constr : `term` + : uconstr : `term` + : type_term `term` + : numgoals + : guard `test` + : assert_fails `tacexpr3` + : assert_succeeds `tacexpr3` + : `atomic_tactic` + : `qualid` `tacarg` ... `tacarg` + : `atom` + atom : `qualid` + : () + : `integer` + : ( `expr` ) + component : `string` | `qualid` + message_token : `string` | `ident` | `integer` + tacarg : `qualid` + : () + : ltac : `atom` + : `term` + let_clause : `ident` [`name` ... `name`] := `expr` + context_rule : `context_hyp`, ..., `context_hyp` |- `cpattern` => `expr` + : `cpattern` => `expr` + : |- `cpattern` => `expr` + : _ => `expr` + context_hyp : `name` : `cpattern` + : `name` := `cpattern` [: `cpattern`] + match_rule : `cpattern` => `expr` + : context [`ident`] [ `cpattern` ] => `expr` + : _ => `expr` + test : `integer` = `integer` + : `integer` (< | <= | > | >=) `integer` + selector : [`ident`] + : `integer` + : (`integer` | `integer` - `integer`), ..., (`integer` | `integer` - `integer`) + toplevel_selector : `selector` + : all + : par + : ! + +.. productionlist:: coq + top : [Local] Ltac `ltac_def` with ... with `ltac_def` + ltac_def : `ident` [`ident` ... `ident`] := `expr` + : `qualid` [`ident` ... `ident`] ::= `expr` + +.. _ltac-semantics: + +Semantics +--------- + +Tactic expressions can only be applied in the context of a proof. The +evaluation yields either a term, an integer or a tactic. Intermediate +results can be terms or integers but the final result must be a tactic +which is then applied to the focused goals. + +There is a special case for ``match goal`` expressions of which the clauses +evaluate to tactics. Such expressions can only be used as end result of +a tactic expression (never as argument of a non-recursive local +definition or of an application). + +The rest of this section explains the semantics of every construction of +|Ltac|. + +Sequence +~~~~~~~~ + +A sequence is an expression of the following form: + +.. tacn:: @expr__1 ; @expr__2 + :name: ltac-seq + + The expression :n:`@expr__1` is evaluated to :n:`v__1`, which must be + a tactic value. The tactic :n:`v__1` is applied to the current goal, + possibly producing more goals. Then :n:`@expr__2` is evaluated to + produce :n:`v__2`, which must be a tactic value. The tactic + :n:`v__2` is applied to all the goals produced by the prior + application. Sequence is associative. + +Local application of tactics +~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Different tactics can be applied to the different goals using the +following form: + +.. tacn:: [> {*| @expr }] + :name: [> ... | ... | ... ] (dispatch) + + The expressions :n:`@expr__i` are evaluated to :n:`v__i`, for + i = 1, ..., n and all have to be tactics. The :n:`v__i` is applied to the + i-th goal, for i = 1, ..., n. It fails if the number of focused goals is not + exactly n. + + .. note:: + + If no tactic is given for the i-th goal, it behaves as if the tactic idtac + were given. For instance, ``[> | auto]`` is a shortcut for ``[> idtac | auto + ]``. + + .. tacv:: [> {*| @expr__i} | @expr .. | {*| @expr__j}] + + In this variant, :n:`@expr` is used for each goal coming after those + covered by the list of :n:`@expr__i` but before those covered by the + list of :n:`@expr__j`. + + .. tacv:: [> {*| @expr} | .. | {*| @expr}] + + In this variant, idtac is used for the goals not covered by the two lists of + :n:`@expr`. + + .. tacv:: [> @expr .. ] + + In this variant, the tactic :n:`@expr` is applied independently to each of + the goals, rather than globally. In particular, if there are no goals, the + tactic is not run at all. A tactic which expects multiple goals, such as + ``swap``, would act as if a single goal is focused. + + .. tacv:: @expr__0 ; [{*| @expr__i}] + + This variant of local tactic application is paired with a sequence. In this + variant, there must be as many :n:`@expr__i` as goals generated + by the application of :n:`@expr__0` to each of the individual goals + independently. All the above variants work in this form too. + Formally, :n:`@expr ; [ ... ]` is equivalent to :n:`[> @expr ; [> ... ] .. ]`. + +.. _goal-selectors: + +Goal selectors +~~~~~~~~~~~~~~ + +We can restrict the application of a tactic to a subset of the currently +focused goals with: + +.. tacn:: @toplevel_selector : @expr + :name: ... : ... (goal selector) + + We can also use selectors as a tactical, which allows to use them nested + in a tactic expression, by using the keyword ``only``: + + .. tacv:: only @selector : @expr + :name: only ... : ... + + When selecting several goals, the tactic :token:`expr` is applied globally to all + selected goals. + + .. tacv:: [@ident] : @expr + + In this variant, :token:`expr` is applied locally to a goal previously named + by the user (see :ref:`existential-variables`). + + .. tacv:: @num : @expr + + In this variant, :token:`expr` is applied locally to the :token:`num`-th goal. + + .. tacv:: {+, @num-@num} : @expr + + In this variant, :n:`@expr` is applied globally to the subset of goals + described by the given ranges. You can write a single ``n`` as a shortcut + for ``n-n`` when specifying multiple ranges. + + .. tacv:: all: @expr + :name: all: ... + + In this variant, :token:`expr` is applied to all focused goals. ``all:`` can only + be used at the toplevel of a tactic expression. + + .. tacv:: !: @expr + + In this variant, if exactly one goal is focused, :token:`expr` is + applied to it. Otherwise the tactic fails. ``!:`` can only be + used at the toplevel of a tactic expression. + + .. tacv:: par: @expr + :name: par: ... + + In this variant, :n:`@expr` is applied to all focused goals in parallel. + The number of workers can be controlled via the command line option + ``-async-proofs-tac-j`` taking as argument the desired number of workers. + Limitations: ``par:`` only works on goals containing no existential + variables and :n:`@expr` must either solve the goal completely or do + nothing (i.e. it cannot make some progress). ``par:`` can only be used at + the toplevel of a tactic expression. + + .. exn:: No such goal. + :name: No such goal. (Goal selector) + :undocumented: + + .. TODO change error message index entry + +For loop +~~~~~~~~ + +There is a for loop that repeats a tactic :token:`num` times: + +.. tacn:: do @num @expr + :name: do + + :n:`@expr` is evaluated to ``v`` which must be a tactic value. This tactic + value ``v`` is applied :token:`num` times. Supposing :token:`num` > 1, after the + first application of ``v``, ``v`` is applied, at least once, to the generated + subgoals and so on. It fails if the application of ``v`` fails before the num + applications have been completed. + +Repeat loop +~~~~~~~~~~~ + +We have a repeat loop with: + +.. tacn:: repeat @expr + :name: repeat + + :n:`@expr` is evaluated to ``v``. If ``v`` denotes a tactic, this tactic is + applied to each focused goal independently. If the application succeeds, the + tactic is applied recursively to all the generated subgoals until it eventually + fails. The recursion stops in a subgoal when the tactic has failed *to make + progress*. The tactic :n:`repeat @expr` itself never fails. + +Error catching +~~~~~~~~~~~~~~ + +We can catch the tactic errors with: + +.. tacn:: try @expr + :name: try + + :n:`@expr` is evaluated to ``v`` which must be a tactic value. The tactic + value ``v`` is applied to each focused goal independently. If the application of + ``v`` fails in a goal, it catches the error and leaves the goal unchanged. If the + level of the exception is positive, then the exception is re-raised with its + level decremented. + +Detecting progress +~~~~~~~~~~~~~~~~~~ + +We can check if a tactic made progress with: + +.. tacn:: progress expr + :name: progress + + :n:`@expr` is evaluated to v which must be a tactic value. The tactic value ``v`` + is applied to each focued subgoal independently. If the application of ``v`` + to one of the focused subgoal produced subgoals equal to the initial + goals (up to syntactical equality), then an error of level 0 is raised. + + .. exn:: Failed to progress. + :undocumented: + +Backtracking branching +~~~~~~~~~~~~~~~~~~~~~~ + +We can branch with the following structure: + +.. tacn:: @expr__1 + @expr__2 + :name: + (backtracking branching) + + :n:`@expr__1` and :n:`@expr__2` are evaluated respectively to :n:`v__1` and + :n:`v__2` which must be tactic values. The tactic value :n:`v__1` is applied to + each focused goal independently and if it fails or a later tactic fails, then + the proof backtracks to the current goal and :n:`v__2` is applied. + + Tactics can be seen as having several successes. When a tactic fails it + asks for more successes of the prior tactics. + :n:`@expr__1 + @expr__2` has all the successes of :n:`v__1` followed by all the + successes of :n:`v__2`. Algebraically, + :n:`(@expr__1 + @expr__2); @expr__3 = (@expr__1; @expr__3) + (@expr__2; @expr__3)`. + + Branching is left-associative. + +First tactic to work +~~~~~~~~~~~~~~~~~~~~ + +Backtracking branching may be too expensive. In this case we may +restrict to a local, left biased, branching and consider the first +tactic to work (i.e. which does not fail) among a panel of tactics: + +.. tacn:: first [{*| @expr}] + :name: first + + The :n:`@expr__i` are evaluated to :n:`v__i` and :n:`v__i` must be + tactic values for i = 1, ..., n. Supposing n > 1, + :n:`first [@expr__1 | ... | @expr__n]` applies :n:`v__1` in each + focused goal independently and stops if it succeeds; otherwise it + tries to apply :n:`v__2` and so on. It fails when there is no + applicable tactic. In other words, + :n:`first [@expr__1 | ... | @expr__n]` behaves, in each goal, as the first + :n:`v__i` to have *at least* one success. + + .. exn:: No applicable tactic. + :undocumented: + + .. tacv:: first @expr + + This is an |Ltac| alias that gives a primitive access to the first + tactical as an |Ltac| definition without going through a parsing rule. It + expects to be given a list of tactics through a ``Tactic Notation``, + allowing to write notations of the following form: + + .. example:: + + .. coqtop:: in + + Tactic Notation "foo" tactic_list(tacs) := first tacs. + +Left-biased branching +~~~~~~~~~~~~~~~~~~~~~ + +Yet another way of branching without backtracking is the following +structure: + +.. tacn:: @expr__1 || @expr__2 + :name: || (left-biased branching) + + :n:`@expr__1` and :n:`@expr__2` are evaluated respectively to :n:`v__1` and + :n:`v__2` which must be tactic values. The tactic value :n:`v__1` is + applied in each subgoal independently and if it fails *to progress* then + :n:`v__2` is applied. :n:`@expr__1 || @expr__2` is + equivalent to :n:`first [ progress @expr__1 | @expr__2 ]` (except that + if it fails, it fails like :n:`v__2`). Branching is left-associative. + +Generalized biased branching +~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +The tactic + +.. tacn:: tryif @expr__1 then @expr__2 else @expr__3 + :name: tryif + + is a generalization of the biased-branching tactics above. The + expression :n:`@expr__1` is evaluated to :n:`v__1`, which is then + applied to each subgoal independently. For each goal where :n:`v__1` + succeeds at least once, :n:`@expr__2` is evaluated to :n:`v__2` which + is then applied collectively to the generated subgoals. The :n:`v__2` + tactic can trigger backtracking points in :n:`v__1`: where :n:`v__1` + succeeds at least once, + :n:`tryif @expr__1 then @expr__2 else @expr__3` is equivalent to + :n:`v__1; v__2`. In each of the goals where :n:`v__1` does not succeed at least + once, :n:`@expr__3` is evaluated in :n:`v__3` which is is then applied to the + goal. + +Soft cut +~~~~~~~~ + +Another way of restricting backtracking is to restrict a tactic to a +single success *a posteriori*: + +.. tacn:: once @expr + :name: once + + :n:`@expr` is evaluated to ``v`` which must be a tactic value. The tactic value + ``v`` is applied but only its first success is used. If ``v`` fails, + :n:`once @expr` fails like ``v``. If ``v`` has at least one success, + :n:`once @expr` succeeds once, but cannot produce more successes. + +Checking the successes +~~~~~~~~~~~~~~~~~~~~~~ + +Coq provides an experimental way to check that a tactic has *exactly +one* success: + +.. tacn:: exactly_once @expr + :name: exactly_once + + :n:`@expr` is evaluated to ``v`` which must be a tactic value. The tactic value + ``v`` is applied if it has at most one success. If ``v`` fails, + :n:`exactly_once @expr` fails like ``v``. If ``v`` has a exactly one success, + :n:`exactly_once @expr` succeeds like ``v``. If ``v`` has two or more + successes, exactly_once expr fails. + + .. warning:: + + The experimental status of this tactic pertains to the fact if ``v`` + performs side effects, they may occur in an unpredictable way. Indeed, + normally ``v`` would only be executed up to the first success until + backtracking is needed, however exactly_once needs to look ahead to see + whether a second success exists, and may run further effects + immediately. + + .. exn:: This tactic has more than one success. + :undocumented: + +Checking the failure +~~~~~~~~~~~~~~~~~~~~ + +Coq provides a derived tactic to check that a tactic *fails*: + +.. tacn:: assert_fails @expr + :name: assert_fails + + This behaves like :n:`tryif @expr then fail 0 tac "succeeds" else idtac`. + +Checking the success +~~~~~~~~~~~~~~~~~~~~ + +Coq provides a derived tactic to check that a tactic has *at least one* +success: + +.. tacn:: assert_succeeds @expr + :name: assert_succeeds + + This behaves like + :n:`tryif (assert_fails tac) then fail 0 tac "fails" else idtac`. + +Solving +~~~~~~~ + +We may consider the first to solve (i.e. which generates no subgoal) +among a panel of tactics: + +.. tacn:: solve [{*| @expr}] + :name: solve + + The :n:`@expr__i` are evaluated to :n:`v__i` and :n:`v__i` must be + tactic values, for i = 1, ..., n. Supposing n > 1, + :n:`solve [@expr__1 | ... | @expr__n]` applies :n:`v__1` to + each goal independently and stops if it succeeds; otherwise it tries to + apply :n:`v__2` and so on. It fails if there is no solving tactic. + + .. exn:: Cannot solve the goal. + :undocumented: + + .. tacv:: solve @expr + + This is an |Ltac| alias that gives a primitive access to the :n:`solve:` + tactical. See the :n:`first` tactical for more information. + +Identity +~~~~~~~~ + +The constant :n:`idtac` is the identity tactic: it leaves any goal unchanged but +it appears in the proof script. + +.. tacn:: idtac {* message_token} + :name: idtac + + This prints the given tokens. Strings and integers are printed + literally. If a (term) variable is given, its contents are printed. + +Failing +~~~~~~~ + +.. tacn:: fail + :name: fail + + This is the always-failing tactic: it does not solve any + goal. It is useful for defining other tacticals since it can be caught by + :tacn:`try`, :tacn:`repeat`, :tacn:`match goal`, or the branching tacticals. + + .. tacv:: fail @num + + The number is the failure level. If no level is specified, it defaults to 0. + The level is used by :tacn:`try`, :tacn:`repeat`, :tacn:`match goal` and the branching + tacticals. If 0, it makes :tacn:`match goal` consider the next clause + (backtracking). If nonzero, the current :tacn:`match goal` block, :tacn:`try`, + :tacn:`repeat`, or branching command is aborted and the level is decremented. In + the case of :n:`+`, a nonzero level skips the first backtrack point, even if + the call to :n:`fail @num` is not enclosed in a :n:`+` command, + respecting the algebraic identity. + + .. tacv:: fail {* message_token} + + The given tokens are used for printing the failure message. + + .. tacv:: fail @num {* message_token} + + This is a combination of the previous variants. + + .. tacv:: gfail + :name: gfail + + This variant fails even when used after :n:`;` and there are no goals left. + Similarly, ``gfail`` fails even when used after ``all:`` and there are no + goals left. See the example for clarification. + + .. tacv:: gfail {* message_token} + gfail @num {* message_token} + + These variants fail with an error message or an error level even if + there are no goals left. Be careful however if Coq terms have to be + printed as part of the failure: term construction always forces the + tactic into the goals, meaning that if there are no goals when it is + evaluated, a tactic call like :n:`let x := H in fail 0 x` will succeed. + + .. exn:: Tactic Failure message (level @num). + :undocumented: + + .. exn:: No such goal. + :name: No such goal. (fail) + :undocumented: + + .. example:: + + .. coqtop:: all fail + + Goal True. + Proof. fail. Abort. + + Goal True. + Proof. trivial; fail. Qed. + + Goal True. + Proof. trivial. fail. Abort. + + Goal True. + Proof. trivial. all: fail. Qed. + + Goal True. + Proof. gfail. Abort. + + Goal True. + Proof. trivial; gfail. Abort. + + Goal True. + Proof. trivial. gfail. Abort. + + Goal True. + Proof. trivial. all: gfail. Abort. + +Timeout +~~~~~~~ + +We can force a tactic to stop if it has not finished after a certain +amount of time: + +.. tacn:: timeout @num @expr + :name: timeout + + :n:`@expr` is evaluated to ``v`` which must be a tactic value. The tactic value + ``v`` is applied normally, except that it is interrupted after :n:`@num` seconds + if it is still running. In this case the outcome is a failure. + + .. warning:: + + For the moment, timeout is based on elapsed time in seconds, + which is very machine-dependent: a script that works on a quick machine + may fail on a slow one. The converse is even possible if you combine a + timeout with some other tacticals. This tactical is hence proposed only + for convenience during debugging or other development phases, we strongly + advise you to not leave any timeout in final scripts. Note also that + this tactical isn’t available on the native Windows port of Coq. + +Timing a tactic +~~~~~~~~~~~~~~~ + +A tactic execution can be timed: + +.. tacn:: time @string @expr + :name: time + + evaluates :n:`@expr` and displays the running time of the tactic expression, whether it + fails or succeeds. In case of several successes, the time for each successive + run is displayed. Time is in seconds and is machine-dependent. The :n:`@string` + argument is optional. When provided, it is used to identify this particular + occurrence of time. + +Timing a tactic that evaluates to a term +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Tactic expressions that produce terms can be timed with the experimental +tactic + +.. tacn:: time_constr expr + :name: time_constr + + which evaluates :n:`@expr ()` and displays the time the tactic expression + evaluated, assuming successful evaluation. Time is in seconds and is + machine-dependent. + + This tactic currently does not support nesting, and will report times + based on the innermost execution. This is due to the fact that it is + implemented using the following internal tactics: + + .. tacn:: restart_timer @string + :name: restart_timer + + Reset a timer + + .. tacn:: finish_timing {? (@string)} @string + :name: finish_timing + + Display an optionally named timer. The parenthesized string argument + is also optional, and determines the label associated with the timer + for printing. + + By copying the definition of :tacn:`time_constr` from the standard library, + users can achive support for a fixed pattern of nesting by passing + different :token:`string` parameters to :tacn:`restart_timer` and + :tacn:`finish_timing` at each level of nesting. + + .. example:: + + .. coqtop:: all abort + + Ltac time_constr1 tac := + let eval_early := match goal with _ => restart_timer "(depth 1)" end in + let ret := tac () in + let eval_early := match goal with _ => finish_timing ( "Tactic evaluation" ) "(depth 1)" end in + ret. + + Goal True. + let v := time_constr + ltac:(fun _ => + let x := time_constr1 ltac:(fun _ => constr:(10 * 10)) in + let y := time_constr1 ltac:(fun _ => eval compute in x) in + y) in + pose v. + +Local definitions +~~~~~~~~~~~~~~~~~ + +Local definitions can be done as follows: + +.. tacn:: let @ident__1 := @expr__1 {* with @ident__i := @expr__i} in @expr + :name: let ... := ... + + each :n:`@expr__i` is evaluated to :n:`v__i`, then, :n:`@expr` is evaluated + by substituting :n:`v__i` to each occurrence of :n:`@ident__i`, for + i = 1, ..., n. There are no dependencies between the :n:`@expr__i` and the + :n:`@ident__i`. + + Local definitions can be made recursive by using :n:`let rec` instead of :n:`let`. + In this latter case, the definitions are evaluated lazily so that the rec + keyword can be used also in non-recursive cases so as to avoid the eager + evaluation of local definitions. + + .. but rec changes the binding!! + +Application +~~~~~~~~~~~ + +An application is an expression of the following form: + +.. tacn:: @qualid {+ @tacarg} + + The reference :n:`@qualid` must be bound to some defined tactic definition + expecting at least as many arguments as the provided :n:`tacarg`. The + expressions :n:`@expr__i` are evaluated to :n:`v__i`, for i = 1, ..., n. + + .. what expressions ?? + +Function construction +~~~~~~~~~~~~~~~~~~~~~ + +A parameterized tactic can be built anonymously (without resorting to +local definitions) with: + +.. tacn:: fun {+ @ident} => @expr + + Indeed, local definitions of functions are a syntactic sugar for binding + a :n:`fun` tactic to an identifier. + +Pattern matching on terms +~~~~~~~~~~~~~~~~~~~~~~~~~ + +We can carry out pattern matching on terms with: + +.. tacn:: match @expr with {+| @cpattern__i => @expr__i} end + + The expression :n:`@expr` is evaluated and should yield a term which is + matched against :n:`cpattern__1`. The matching is non-linear: if a + metavariable occurs more than once, it should match the same expression + every time. It is first-order except on the variables of the form :n:`@?id` + that occur in head position of an application. For these variables, the + matching is second-order and returns a functional term. + + Alternatively, when a metavariable of the form :n:`?id` occurs under binders, + say :n:`x__1, …, x__n` and the expression matches, the + metavariable is instantiated by a term which can then be used in any + context which also binds the variables :n:`x__1, …, x__n` with + same types. This provides with a primitive form of matching under + context which does not require manipulating a functional term. + + If the matching with :n:`@cpattern__1` succeeds, then :n:`@expr__1` is + evaluated into some value by substituting the pattern matching + instantiations to the metavariables. If :n:`@expr__1` evaluates to a + tactic and the match expression is in position to be applied to a goal + (e.g. it is not bound to a variable by a :n:`let in`), then this tactic is + applied. If the tactic succeeds, the list of resulting subgoals is the + result of the match expression. If :n:`@expr__1` does not evaluate to a + tactic or if the match expression is not in position to be applied to a + goal, then the result of the evaluation of :n:`@expr__1` is the result + of the match expression. + + If the matching with :n:`@cpattern__1` fails, or if it succeeds but the + evaluation of :n:`@expr__1` fails, or if the evaluation of + :n:`@expr__1` succeeds but returns a tactic in execution position whose + execution fails, then :n:`cpattern__2` is used and so on. The pattern + :n:`_` matches any term and shadows all remaining patterns if any. If all + clauses fail (in particular, there is no pattern :n:`_`) then a + no-matching-clause error is raised. + + Failures in subsequent tactics do not cause backtracking to select new + branches or inside the right-hand side of the selected branch even if it + has backtracking points. + + .. exn:: No matching clauses for match. + + No pattern can be used and, in particular, there is no :n:`_` pattern. + + .. exn:: Argument of match does not evaluate to a term. + + This happens when :n:`@expr` does not denote a term. + + .. tacv:: multimatch @expr with {+| @cpattern__i => @expr__i} end + + Using multimatch instead of match will allow subsequent tactics to + backtrack into a right-hand side tactic which has backtracking points + left and trigger the selection of a new matching branch when all the + backtracking points of the right-hand side have been consumed. + + The syntax :n:`match …` is, in fact, a shorthand for :n:`once multimatch …`. + + .. tacv:: lazymatch @expr with {+| @cpattern__i => @expr__i} end + + Using lazymatch instead of match will perform the same pattern + matching procedure but will commit to the first matching branch + rather than trying a new matching if the right-hand side fails. If + the right-hand side of the selected branch is a tactic with + backtracking points, then subsequent failures cause this tactic to + backtrack. + + .. tacv:: context @ident [@cpattern] + + This special form of patterns matches any term with a subterm matching + cpattern. If there is a match, the optional :n:`@ident` is assigned the "matched + context", i.e. the initial term where the matched subterm is replaced by a + hole. The example below will show how to use such term contexts. + + If the evaluation of the right-hand-side of a valid match fails, the next + matching subterm is tried. If no further subterm matches, the next clause + is tried. Matching subterms are considered top-bottom and from left to + right (with respect to the raw printing obtained by setting option + :flag:`Printing All`). + + .. example:: + + .. coqtop:: all abort + + Ltac f x := + match x with + context f [S ?X] => + idtac X; (* To display the evaluation order *) + assert (p := eq_refl 1 : X=1); (* To filter the case X=1 *) + let x:= context f[O] in assert (x=O) (* To observe the context *) + end. + Goal True. + f (3+4). + +.. _ltac-match-goal: + +Pattern matching on goals +~~~~~~~~~~~~~~~~~~~~~~~~~ + +We can perform pattern matching on goals using the following expression: + +.. we should provide the full grammar here + +.. tacn:: match goal with {+| {+ hyp} |- @cpattern => @expr } | _ => @expr end + :name: match goal + + If each hypothesis pattern :n:`hyp`\ :sub:`1,i`, with i = 1, ..., m\ :sub:`1` is + matched (non-linear first-order unification) by a hypothesis of the + goal and if :n:`cpattern_1` is matched by the conclusion of the goal, + then :n:`@expr__1` is evaluated to :n:`v__1` by substituting the + pattern matching to the metavariables and the real hypothesis names + bound to the possible hypothesis names occurring in the hypothesis + patterns. If :n:`v__1` is a tactic value, then it is applied to the + goal. If this application fails, then another combination of hypotheses + is tried with the same proof context pattern. If there is no other + combination of hypotheses then the second proof context pattern is tried + and so on. If the next to last proof context pattern fails then + the last :n:`@expr` is evaluated to :n:`v` and :n:`v` is + applied. Note also that matching against subterms (using the :n:`context + @ident [ @cpattern ]`) is available and is also subject to yielding several + matchings. + + Failures in subsequent tactics do not cause backtracking to select new + branches or combinations of hypotheses, or inside the right-hand side of + the selected branch even if it has backtracking points. + + .. exn:: No matching clauses for match goal. + + No clause succeeds, i.e. all matching patterns, if any, fail at the + application of the right-hand-side. + + .. note:: + + It is important to know that each hypothesis of the goal can be matched + by at most one hypothesis pattern. The order of matching is the + following: hypothesis patterns are examined from right to left + (i.e. hyp\ :sub:`i,m`\ :sub:`i`` before hyp\ :sub:`i,1`). For each + hypothesis pattern, the goal hypotheses are matched in order (newest + first), but it possible to reverse this order (oldest first) + with the :n:`match reverse goal with` variant. + + .. tacv:: multimatch goal with {+| {+ hyp} |- @cpattern => @expr } | _ => @expr end + + Using :n:`multimatch` instead of :n:`match` will allow subsequent tactics + to backtrack into a right-hand side tactic which has backtracking points + left and trigger the selection of a new matching branch or combination of + hypotheses when all the backtracking points of the right-hand side have + been consumed. + + The syntax :n:`match [reverse] goal …` is, in fact, a shorthand for + :n:`once multimatch [reverse] goal …`. + + .. tacv:: lazymatch goal with {+| {+ hyp} |- @cpattern => @expr } | _ => @expr end + + Using lazymatch instead of match will perform the same pattern matching + procedure but will commit to the first matching branch with the first + matching combination of hypotheses rather than trying a new matching if + the right-hand side fails. If the right-hand side of the selected branch + is a tactic with backtracking points, then subsequent failures cause + this tactic to backtrack. + +Filling a term context +~~~~~~~~~~~~~~~~~~~~~~ + +The following expression is not a tactic in the sense that it does not +produce subgoals but generates a term to be used in tactic expressions: + +.. tacn:: context @ident [@expr] + + :n:`@ident` must denote a context variable bound by a context pattern of a + match expression. This expression evaluates replaces the hole of the + value of :n:`@ident` by the value of :n:`@expr`. + + .. exn:: Not a context variable. + :undocumented: + + .. exn:: Unbound context identifier @ident. + :undocumented: + +Generating fresh hypothesis names +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Tactics sometimes have to generate new names for hypothesis. Letting the +system decide a name with the intro tactic is not so good since it is +very awkward to retrieve the name the system gave. The following +expression returns an identifier: + +.. tacn:: fresh {* component} + + It evaluates to an identifier unbound in the goal. This fresh identifier + is obtained by concatenating the value of the :n:`@component`\ s (each of them + is, either a :n:`@qualid` which has to refer to a (unqualified) name, or + directly a name denoted by a :n:`@string`). + + If the resulting name is already used, it is padded with a number so that it + becomes fresh. If no component is given, the name is a fresh derivative of + the name ``H``. + +Computing in a constr +~~~~~~~~~~~~~~~~~~~~~ + +Evaluation of a term can be performed with: + +.. tacn:: eval @redexpr in @term + + where :n:`@redexpr` is a reduction tactic among :tacn:`red`, :tacn:`hnf`, + :tacn:`compute`, :tacn:`simpl`, :tacn:`cbv`, :tacn:`lazy`, :tacn:`unfold`, + :tacn:`fold`, :tacn:`pattern`. + +Recovering the type of a term +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. tacn:: type of @term + + This tactic returns the type of :token:`term`. + +Manipulating untyped terms +~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. tacn:: uconstr : @term + + The terms built in |Ltac| are well-typed by default. It may not be + appropriate for building large terms using a recursive |Ltac| function: the + term has to be entirely type checked at each step, resulting in potentially + very slow behavior. It is possible to build untyped terms using |Ltac| with + the :n:`uconstr : @term` syntax. + +.. tacn:: type_term @term + + An untyped term, in |Ltac|, can contain references to hypotheses or to + |Ltac| variables containing typed or untyped terms. An untyped term can be + type checked using the function type_term whose argument is parsed as an + untyped term and returns a well-typed term which can be used in tactics. + +Untyped terms built using :n:`uconstr :` can also be used as arguments to the +:tacn:`refine` tactic. In that case the untyped term is type +checked against the conclusion of the goal, and the holes which are not solved +by the typing procedure are turned into new subgoals. + +Counting the goals +~~~~~~~~~~~~~~~~~~ + +.. tacn:: numgoals + + The number of goals under focus can be recovered using the :n:`numgoals` + function. Combined with the guard command below, it can be used to + branch over the number of goals produced by previous tactics. + + .. example:: + + .. coqtop:: in + + Ltac pr_numgoals := let n := numgoals in idtac "There are" n "goals". + + Goal True /\ True /\ True. + split;[|split]. + + .. coqtop:: all abort + + all:pr_numgoals. + +Testing boolean expressions +~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. tacn:: guard @test + :name: guard + + The :tacn:`guard` tactic tests a boolean expression, and fails if the expression + evaluates to false. If the expression evaluates to true, it succeeds + without affecting the proof. + + The accepted tests are simple integer comparisons. + + .. example:: + + .. coqtop:: in + + Goal True /\ True /\ True. + split;[|split]. + + .. coqtop:: all + + all:let n:= numgoals in guard n<4. + Fail all:let n:= numgoals in guard n=2. + + .. exn:: Condition not satisfied. + :undocumented: + +Proving a subgoal as a separate lemma +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. tacn:: abstract @expr + :name: abstract + + From the outside, :n:`abstract @expr` is the same as :n:`solve @expr`. + Internally it saves an auxiliary lemma called ``ident_subproofn`` where + ``ident`` is the name of the current goal and ``n`` is chosen so that this is + a fresh name. Such an auxiliary lemma is inlined in the final proof term. + + This tactical is useful with tactics such as :tacn:`omega` or + :tacn:`discriminate` that generate huge proof terms. With that tool the user + can avoid the explosion at time of the Save command without having to cut + manually the proof in smaller lemmas. + + It may be useful to generate lemmas minimal w.r.t. the assumptions they + depend on. This can be obtained thanks to the option below. + + .. warning:: + + The abstract tactic, while very useful, still has some known + limitations, see https://github.com/coq/coq/issues/9146 for more + details. Thus we recommend using it caution in some + "non-standard" contexts. In particular, ``abstract`` won't + properly work when used inside quotations ``ltac:(...)``, or + if used as part of typeclass resolution, it may produce wrong + terms when in universe polymorphic mode. + + .. tacv:: abstract @expr using @ident + + Give explicitly the name of the auxiliary lemma. + + .. warning:: + + Use this feature at your own risk; explicitly named and reused subterms + don’t play well with asynchronous proofs. + + .. tacv:: transparent_abstract @expr + :name: transparent_abstract + + Save the subproof in a transparent lemma rather than an opaque one. + + .. warning:: + + Use this feature at your own risk; building computationally relevant + terms with tactics is fragile. + + .. tacv:: transparent_abstract @expr using @ident + + Give explicitly the name of the auxiliary transparent lemma. + + .. warning:: + + Use this feature at your own risk; building computationally relevant terms + with tactics is fragile, and explicitly named and reused subterms + don’t play well with asynchronous proofs. + + .. exn:: Proof is not complete. + :name: Proof is not complete. (abstract) + :undocumented: + +Tactic toplevel definitions +--------------------------- + +Defining |Ltac| functions +~~~~~~~~~~~~~~~~~~~~~~~~~ + +Basically, |Ltac| toplevel definitions are made as follows: + +.. cmd:: Ltac @ident {* @ident} := @expr + + This defines a new |Ltac| function that can be used in any tactic + script or new |Ltac| toplevel definition. + + .. note:: + + The preceding definition can equivalently be written: + + :n:`Ltac @ident := fun {+ @ident} => @expr` + + Recursive and mutual recursive function definitions are also possible + with the syntax: + + .. cmdv:: Ltac @ident {* @ident} {* with @ident {* @ident}} := @expr + + It is also possible to *redefine* an existing user-defined tactic using the syntax: + + .. cmdv:: Ltac @qualid {* @ident} ::= @expr + + A previous definition of qualid must exist in the environment. The new + definition will always be used instead of the old one and it goes across + module boundaries. + + If preceded by the keyword Local the tactic definition will not be + exported outside the current module. + +Printing |Ltac| tactics +~~~~~~~~~~~~~~~~~~~~~~~ + +.. cmd:: Print Ltac @qualid + + Defined |Ltac| functions can be displayed using this command. + +.. cmd:: Print Ltac Signatures + + This command displays a list of all user-defined tactics, with their arguments. + +Debugging |Ltac| tactics +------------------------ + +Backtraces +~~~~~~~~~~ + +.. flag:: Ltac Backtrace + + Setting this flag displays a backtrace on Ltac failures that can be useful + to find out what went wrong. It is disabled by default for performance + reasons. + +Info trace +~~~~~~~~~~ + +.. cmd:: Info @num @expr + :name: Info + + This command can be used to print the trace of the path eventually taken by an + |Ltac| script. That is, the list of executed tactics, discarding + all the branches which have failed. To that end the :cmd:`Info` command can be + used with the following syntax. + + + The number :n:`@num` is the unfolding level of tactics in the trace. At level + 0, the trace contains a sequence of tactics in the actual script, at level 1, + the trace will be the concatenation of the traces of these tactics, etc… + + .. example:: + + .. coqtop:: in reset + + Ltac t x := exists x; reflexivity. + Goal exists n, n=0. + + .. coqtop:: all + + Info 0 t 1||t 0. + + .. coqtop:: in + + Undo. + + .. coqtop:: all + + Info 1 t 1||t 0. + + The trace produced by :cmd:`Info` tries its best to be a reparsable + |Ltac| script, but this goal is not achievable in all generality. + So some of the output traces will contain oddities. + + As an additional help for debugging, the trace produced by :cmd:`Info` contains + (in comments) the messages produced by the :tacn:`idtac` tactical at the right + position in the script. In particular, the calls to idtac in branches which failed are + not printed. + + .. opt:: Info Level @num + :name: Info Level + + This option is an alternative to the :cmd:`Info` command. + + This will automatically print the same trace as :n:`Info @num` at each + tactic call. The unfolding level can be overridden by a call to the + :cmd:`Info` command. + +Interactive debugger +~~~~~~~~~~~~~~~~~~~~ + +.. flag:: Ltac Debug + + This option governs the step-by-step debugger that comes with the |Ltac| interpreter. + +When the debugger is activated, it stops at every step of the evaluation of +the current |Ltac| expression and prints information on what it is doing. +The debugger stops, prompting for a command which can be one of the +following: + ++-----------------+-----------------------------------------------+ +| simple newline: | go to the next step | ++-----------------+-----------------------------------------------+ +| h: | get help | ++-----------------+-----------------------------------------------+ +| x: | exit current evaluation | ++-----------------+-----------------------------------------------+ +| s: | continue current evaluation without stopping | ++-----------------+-----------------------------------------------+ +| r n: | advance n steps further | ++-----------------+-----------------------------------------------+ +| r string: | advance up to the next call to “idtac string” | ++-----------------+-----------------------------------------------+ + +.. exn:: Debug mode not available in the IDE + :undocumented: + +A non-interactive mode for the debugger is available via the option: + +.. flag:: Ltac Batch Debug + + This option has the effect of presenting a newline at every prompt, when + the debugger is on. The debug log thus created, which does not require + user input to generate when this option is set, can then be run through + external tools such as diff. + +Profiling |Ltac| tactics +~~~~~~~~~~~~~~~~~~~~~~~~ + +It is possible to measure the time spent in invocations of primitive +tactics as well as tactics defined in |Ltac| and their inner +invocations. The primary use is the development of complex tactics, +which can sometimes be so slow as to impede interactive usage. The +reasons for the performence degradation can be intricate, like a slowly +performing |Ltac| match or a sub-tactic whose performance only +degrades in certain situations. The profiler generates a call tree and +indicates the time spent in a tactic depending on its calling context. Thus +it allows to locate the part of a tactic definition that contains the +performance issue. + +.. flag:: Ltac Profiling + + This option enables and disables the profiler. + +.. cmd:: Show Ltac Profile + + Prints the profile + + .. cmdv:: Show Ltac Profile @string + + Prints a profile for all tactics that start with :n:`@string`. Append a period + (.) to the string if you only want exactly that name. + +.. cmd:: Reset Ltac Profile + + Resets the profile, that is, deletes all accumulated information. + + .. warning:: + + Backtracking across a :cmd:`Reset Ltac Profile` will not restore the information. + +.. coqtop:: reset in + + Require Import Coq.omega.Omega. + + Ltac mytauto := tauto. + Ltac tac := intros; repeat split; omega || mytauto. + + Notation max x y := (x + (y - x)) (only parsing). + + Goal forall x y z A B C D E F G H I J K L M N O P Q R S T U V W X Y Z, + max x (max y z) = max (max x y) z /\ max x (max y z) = max (max x y) z + /\ + (A /\ B /\ C /\ D /\ E /\ F /\ G /\ H /\ I /\ J /\ K /\ L /\ M /\ + N /\ O /\ P /\ Q /\ R /\ S /\ T /\ U /\ V /\ W /\ X /\ Y /\ Z + -> + Z /\ Y /\ X /\ W /\ V /\ U /\ T /\ S /\ R /\ Q /\ P /\ O /\ N /\ + M /\ L /\ K /\ J /\ I /\ H /\ G /\ F /\ E /\ D /\ C /\ B /\ A). + Proof. + +.. coqtop:: all + + Set Ltac Profiling. + tac. + Show Ltac Profile. + Show Ltac Profile "omega". + +.. coqtop:: in + + Abort. + Unset Ltac Profiling. + +.. tacn:: start ltac profiling + :name: start ltac profiling + + This tactic behaves like :tacn:`idtac` but enables the profiler. + +.. tacn:: stop ltac profiling + :name: stop ltac profiling + + Similarly to :tacn:`start ltac profiling`, this tactic behaves like + :tacn:`idtac`. Together, they allow you to exclude parts of a proof script + from profiling. + +.. tacn:: reset ltac profile + :name: reset ltac profile + + This tactic behaves like the corresponding vernacular command + and allow displaying and resetting the profile from tactic scripts for + benchmarking purposes. + +.. tacn:: show ltac profile + :name: show ltac profile + + This tactic behaves like the corresponding vernacular command + and allow displaying and resetting the profile from tactic scripts for + benchmarking purposes. + +.. tacn:: show ltac profile @string + :name: show ltac profile + + This tactic behaves like the corresponding vernacular command + and allow displaying and resetting the profile from tactic scripts for + benchmarking purposes. + +You can also pass the ``-profile-ltac`` command line option to ``coqc``, which +turns the :flag:`Ltac Profiling` option on at the beginning of each document, +and performs a :cmd:`Show Ltac Profile` at the end. + +.. warning:: + + Note that the profiler currently does not handle backtracking into + multi-success tactics, and issues a warning to this effect in many cases + when such backtracking occurs. + +Run-time optimization tactic +~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. tacn:: optimize_heap + :name: optimize_heap + + This tactic behaves like :n:`idtac`, except that running it compacts the + heap in the OCaml run-time system. It is analogous to the Vernacular + command :cmd:`Optimize Heap`. diff --git a/doc/sphinx/proof-engine/proof-handling.rst b/doc/sphinx/proof-engine/proof-handling.rst new file mode 100644 index 0000000000..16b158c397 --- /dev/null +++ b/doc/sphinx/proof-engine/proof-handling.rst @@ -0,0 +1,832 @@ +.. _proofhandling: + +------------------- + Proof handling +------------------- + +In |Coq|’s proof editing mode all top-level commands documented in +Chapter :ref:`vernacularcommands` remain available and the user has access to specialized +commands dealing with proof development pragmas documented in this +section. They can also use some other specialized commands called +*tactics*. They are the very tools allowing the user to deal with +logical reasoning. They are documented in Chapter :ref:`tactics`. + +Coq user interfaces usually have a way of marking whether the user has +switched to proof editing mode. For instance, in coqtop the prompt ``Coq <`` is changed into +:n:`@ident <` where :token:`ident` is the declared name of the theorem currently edited. + +At each stage of a proof development, one has a list of goals to +prove. Initially, the list consists only in the theorem itself. After +having applied some tactics, the list of goals contains the subgoals +generated by the tactics. + +To each subgoal is associated a number of hypotheses called the *local context* +of the goal. Initially, the local context contains the local variables and +hypotheses of the current section (see Section :ref:`gallina-assumptions`) and +the local variables and hypotheses of the theorem statement. It is enriched by +the use of certain tactics (see e.g. :tacn:`intro`). + +When a proof is completed, the message ``Proof completed`` is displayed. +One can then register this proof as a defined constant in the +environment. Because there exists a correspondence between proofs and +terms of λ-calculus, known as the *Curry-Howard isomorphism* +:cite:`How80,Bar81,Gir89,H89`, |Coq| stores proofs as terms of |Cic|. Those +terms are called *proof terms*. + + +.. exn:: No focused proof. + + Coq raises this error message when one attempts to use a proof editing command + out of the proof editing mode. + +.. _proof-editing-mode: + +Switching on/off the proof editing mode +------------------------------------------- + +The proof editing mode is entered by asserting a statement, which typically is +the assertion of a theorem using an assertion command like :cmd:`Theorem`. The +list of assertion commands is given in :ref:`Assertions`. The command +:cmd:`Goal` can also be used. + +.. cmd:: Goal @form + + This is intended for quick assertion of statements, without knowing in + advance which name to give to the assertion, typically for quick + testing of the provability of a statement. If the proof of the + statement is eventually completed and validated, the statement is then + bound to the name ``Unnamed_thm`` (or a variant of this name not already + used for another statement). + +.. cmd:: Qed + + This command is available in interactive editing proof mode when the + proof is completed. Then :cmd:`Qed` extracts a proof term from the proof + script, switches back to Coq top-level and attaches the extracted + proof term to the declared name of the original goal. This name is + added to the environment as an opaque constant. + + .. exn:: Attempt to save an incomplete proof. + :undocumented: + + .. note:: + + Sometimes an error occurs when building the proof term, because + tactics do not enforce completely the term construction + constraints. + + The user should also be aware of the fact that since the + proof term is completely rechecked at this point, one may have to wait + a while when the proof is large. In some exceptional cases one may + even incur a memory overflow. + + .. cmdv:: Defined + :name: Defined + + Same as :cmd:`Qed` but the proof is then declared transparent, which means + that its content can be explicitly used for type checking and that it can be + unfolded in conversion tactics (see :ref:`performingcomputations`, + :cmd:`Opaque`, :cmd:`Transparent`). + + .. cmdv:: Save @ident + :name: Save + + Forces the name of the original goal to be :token:`ident`. This + command (and the following ones) can only be used if the original goal + has been opened using the :cmd:`Goal` command. + +.. cmd:: Admitted + + This command is available in interactive editing mode to give up + the current proof and declare the initial goal as an axiom. + +.. cmd:: Abort + + This command cancels the current proof development, switching back to + the previous proof development, or to the |Coq| toplevel if no other + proof was edited. + + .. exn:: No focused proof (No proof-editing in progress). + :undocumented: + + .. cmdv:: Abort @ident + + Aborts the editing of the proof named :token:`ident` (in case you have + nested proofs). + + .. seealso:: :flag:`Nested Proofs Allowed` + + .. cmdv:: Abort All + + Aborts all current goals. + +.. cmd:: Proof @term + :name: Proof `term` + + This command applies in proof editing mode. It is equivalent to + :n:`exact @term. Qed.` + That is, you have to give the full proof in one gulp, as a + proof term (see Section :ref:`applyingtheorems`). + +.. cmd:: Proof + + Is a no-op which is useful to delimit the sequence of tactic commands + which start a proof, after a :cmd:`Theorem` command. It is a good practice to + use :cmd:`Proof` as an opening parenthesis, closed in the script with a + closing :cmd:`Qed`. + + .. seealso:: :cmd:`Proof with` + +.. cmd:: Proof using {+ @ident } + + This command applies in proof editing mode. It declares the set of + section variables (see :ref:`gallina-assumptions`) used by the proof. + At :cmd:`Qed` time, the + system will assert that the set of section variables actually used in + the proof is a subset of the declared one. + + The set of declared variables is closed under type dependency. For + example, if ``T`` is a variable and ``a`` is a variable of type + ``T``, then the commands ``Proof using a`` and ``Proof using T a`` + are equivalent. + + .. cmdv:: Proof using {+ @ident } with @tactic + + Combines in a single line :cmd:`Proof with` and :cmd:`Proof using`. + + .. seealso:: :ref:`tactics-implicit-automation` + + .. cmdv:: Proof using All + + Use all section variables. + + .. cmdv:: Proof using {? Type } + + Use only section variables occurring in the statement. + + .. cmdv:: Proof using Type* + + The ``*`` operator computes the forward transitive closure. E.g. if the + variable ``H`` has type ``p < 5`` then ``H`` is in ``p*`` since ``p`` occurs in the type + of ``H``. ``Type*`` is the forward transitive closure of the entire set of + section variables occurring in the statement. + + .. cmdv:: Proof using -({+ @ident }) + + Use all section variables except the list of :token:`ident`. + + .. cmdv:: Proof using @collection1 + @collection2 + + Use section variables from the union of both collections. + See :ref:`nameaset` to know how to form a named collection. + + .. cmdv:: Proof using @collection1 - @collection2 + + Use section variables which are in the first collection but not in the + second one. + + .. cmdv:: Proof using @collection - ({+ @ident }) + + Use section variables which are in the first collection but not in the + list of :token:`ident`. + + .. cmdv:: Proof using @collection * + + Use section variables in the forward transitive closure of the collection. + The ``*`` operator binds stronger than ``+`` and ``-``. + + +Proof using options +``````````````````` + +The following options modify the behavior of ``Proof using``. + + +.. opt:: Default Proof Using "@expression" + :name: Default Proof Using + + Use :n:`@expression` as the default ``Proof using`` value. E.g. ``Set Default + Proof Using "a b"`` will complete all ``Proof`` commands not followed by a + ``using`` part with ``using a b``. + + +.. flag:: Suggest Proof Using + + When :cmd:`Qed` is performed, suggest a ``using`` annotation if the user did not + provide one. + +.. _`nameaset`: + +Name a set of section hypotheses for ``Proof using`` +```````````````````````````````````````````````````` + +.. cmd:: Collection @ident := @expression + + This can be used to name a set of section + hypotheses, with the purpose of making ``Proof using`` annotations more + compact. + + .. example:: + + Define the collection named ``Some`` containing ``x``, ``y`` and ``z``:: + + Collection Some := x y z. + + Define the collection named ``Fewer`` containing only ``x`` and ``y``:: + + Collection Fewer := Some - z + + Define the collection named ``Many`` containing the set union or set + difference of ``Fewer`` and ``Some``:: + + Collection Many := Fewer + Some + Collection Many := Fewer - Some + + Define the collection named ``Many`` containing the set difference of + ``Fewer`` and the unnamed collection ``x y``:: + + Collection Many := Fewer - (x y) + + + +.. cmd:: Existential @num := @term + + This command instantiates an existential variable. :token:`num` is an index in + the list of uninstantiated existential variables displayed by :cmd:`Show Existentials`. + + This command is intended to be used to instantiate existential + variables when the proof is completed but some uninstantiated + existential variables remain. To instantiate existential variables + during proof edition, you should use the tactic :tacn:`instantiate`. + +.. cmd:: Grab Existential Variables + + This command can be run when a proof has no more goal to be solved but + has remaining uninstantiated existential variables. It takes every + uninstantiated existential variable and turns it into a goal. + + +Navigation in the proof tree +-------------------------------- + +.. cmd:: Undo + + This command cancels the effect of the last command. Thus, it + backtracks one step. + +.. cmdv:: Undo @num + + Repeats Undo :token:`num` times. + +.. cmdv:: Restart + :name: Restart + + This command restores the proof editing process to the original goal. + + .. exn:: No focused proof to restart. + :undocumented: + +.. cmd:: Focus + + This focuses the attention on the first subgoal to prove and the + printing of the other subgoals is suspended until the focused subgoal + is solved or unfocused. This is useful when there are many current + subgoals which clutter your screen. + + .. deprecated:: 8.8 + + Prefer the use of bullets or focusing brackets (see below). + +.. cmdv:: Focus @num + + This focuses the attention on the :token:`num` th subgoal to prove. + + .. deprecated:: 8.8 + + Prefer the use of focusing brackets with a goal selector (see below). + +.. cmd:: Unfocus + + This command restores to focus the goal that were suspended by the + last :cmd:`Focus` command. + + .. deprecated:: 8.8 + +.. cmd:: Unfocused + + Succeeds if the proof is fully unfocused, fails if there are some + goals out of focus. + +.. _curly-braces: + +.. index:: { + } + +.. cmd:: %{ %| %} + + The command ``{`` (without a terminating period) focuses on the first + goal, much like :cmd:`Focus` does, however, the subproof can only be + unfocused when it has been fully solved ( *i.e.* when there is no + focused goal left). Unfocusing is then handled by ``}`` (again, without a + terminating period). See also an example in the next section. + + Note that when a focused goal is proved a message is displayed + together with a suggestion about the right bullet or ``}`` to unfocus it + or focus the next one. + + .. cmdv:: @num: %{ + + This focuses on the :token:`num`\-th subgoal to prove. + + .. cmdv:: [@ident]: %{ + + This focuses on the named goal :token:`ident`. + + .. note:: + + Goals are just existential variables and existential variables do not + get a name by default. You can give a name to a goal by using :n:`refine ?[@ident]`. + You may also wrap this in an Ltac-definition like: + + .. coqtop:: in + + Ltac name_goal name := refine ?[name]. + + .. seealso:: :ref:`existential-variables` + + .. example:: + + This first example uses the Ltac definition above, and the named goals + only serve for documentation. + + .. coqtop:: all + + Goal forall n, n + 0 = n. + Proof. + induction n; [ name_goal base | name_goal step ]. + [base]: { + + .. coqtop:: all + + reflexivity. + + .. coqtop:: in + + } + + .. coqtop:: all + + [step]: { + + .. coqtop:: all + + simpl. + f_equal. + assumption. + } + Qed. + + This can also be a way of focusing on a shelved goal, for instance: + + .. coqtop:: all + + Goal exists n : nat, n = n. + eexists ?[x]. + reflexivity. + [x]: exact 0. + Qed. + + .. exn:: This proof is focused, but cannot be unfocused this way. + + You are trying to use ``}`` but the current subproof has not been fully solved. + + .. exn:: No such goal (@num). + :undocumented: + + .. exn:: No such goal (@ident). + :undocumented: + + .. exn:: Brackets do not support multi-goal selectors. + + Brackets are used to focus on a single goal given either by its position + or by its name if it has one. + + .. seealso:: The error messages about bullets below. + +.. _bullets: + +Bullets +``````` + +Alternatively to ``{`` and ``}``, proofs can be structured with bullets. The +use of a bullet ``b`` for the first time focuses on the first goal ``g``, the +same bullet cannot be used again until the proof of ``g`` is completed, +then it is mandatory to focus the next goal with ``b``. The consequence is +that ``g`` and all goals present when ``g`` was focused are focused with the +same bullet ``b``. See the example below. + +Different bullets can be used to nest levels. The scope of bullet does +not go beyond enclosing ``{`` and ``}``, so bullets can be reused as further +nesting levels provided they are delimited by these. Bullets are made of +repeated ``-``, ``+`` or ``*`` symbols: + +.. prodn:: bullet ::= {+ - } %| {+ + } %| {+ * } + +Note again that when a focused goal is proved a message is displayed +together with a suggestion about the right bullet or ``}`` to unfocus it +or focus the next one. + +.. note:: + + In Proof General (``Emacs`` interface to |Coq|), you must use + bullets with the priority ordering shown above to have a correct + indentation. For example ``-`` must be the outer bullet and ``**`` the inner + one in the example below. + +The following example script illustrates all these features: + +.. example:: + + .. coqtop:: all + + Goal (((True /\ True) /\ True) /\ True) /\ True. + Proof. + split. + - split. + + split. + ** { split. + - trivial. + - trivial. + } + ** trivial. + + trivial. + - assert True. + { trivial. } + assumption. + Qed. + +.. exn:: Wrong bullet @bullet__1: Current bullet @bullet__2 is not finished. + + Before using bullet :n:`@bullet__1` again, you should first finish proving + the current focused goal. + Note that :n:`@bullet__1` and :n:`@bullet__2` may be the same. + +.. exn:: Wrong bullet @bullet__1: Bullet @bullet__2 is mandatory here. + + You must put :n:`@bullet__2` to focus on the next goal. No other bullet is + allowed here. + +.. exn:: No such goal. Focus next goal with bullet @bullet. + + You tried to apply a tactic but no goals were under focus. + Using :n:`@bullet` is mandatory here. + +.. FIXME: the :noindex: below works around a Sphinx issue. + (https://github.com/sphinx-doc/sphinx/issues/4979) + It should be removed once that issue is fixed. + +.. exn:: No such goal. Try unfocusing with %}. + :noindex: + + You just finished a goal focused by ``{``, you must unfocus it with ``}``. + +Set Bullet Behavior +``````````````````` +.. opt:: Bullet Behavior %( "None" %| "Strict Subproofs" %) + :name: Bullet Behavior + + This option controls the bullet behavior and can take two possible values: + + - "None": this makes bullets inactive. + - "Strict Subproofs": this makes bullets active (this is the default behavior). + +.. _requestinginformation: + +Requesting information +---------------------- + + +.. cmd:: Show + + This command displays the current goals. + + .. exn:: No focused proof. + :undocumented: + + .. cmdv:: Show @num + + Displays only the :token:`num`\-th subgoal. + + .. exn:: No such goal. + :undocumented: + + .. cmdv:: Show @ident + + Displays the named goal :token:`ident`. This is useful in + particular to display a shelved goal but only works if the + corresponding existential variable has been named by the user + (see :ref:`existential-variables`) as in the following example. + + .. example:: + + .. coqtop:: all abort + + Goal exists n, n = 0. + eexists ?[n]. + Show n. + + .. cmdv:: Show Script + :name: Show Script + + Displays the whole list of tactics applied from the + beginning of the current proof. This tactics script may contain some + holes (subgoals not yet proved). They are printed under the form + + ``<Your Tactic Text here>``. + + .. deprecated:: 8.10 + + Please use a text editor. + + .. cmdv:: Show Proof + :name: Show Proof + + It displays the proof term generated by the tactics + that have been applied. If the proof is not completed, this term + contain holes, which correspond to the sub-terms which are still to be + constructed. These holes appear as a question mark indexed by an + integer, and applied to the list of variables in the context, since it + may depend on them. The types obtained by abstracting away the context + from the type of each placeholder are also printed. + + .. cmdv:: Show Conjectures + :name: Show Conjectures + + It prints the list of the names of all the + theorems that are currently being proved. As it is possible to start + proving a previous lemma during the proof of a theorem, this list may + contain several names. + + .. cmdv:: Show Intro + :name: Show Intro + + If the current goal begins by at least one product, + this command prints the name of the first product, as it would be + generated by an anonymous :tacn:`intro`. The aim of this command is to ease + the writing of more robust scripts. For example, with an appropriate + Proof General macro, it is possible to transform any anonymous :tacn:`intro` + into a qualified one such as ``intro y13``. In the case of a non-product + goal, it prints nothing. + + .. cmdv:: Show Intros + :name: Show Intros + + This command is similar to the previous one, it + simulates the naming process of an :tacn:`intros`. + + .. cmdv:: Show Existentials + :name: Show Existentials + + It displays the set of all uninstantiated + existential variables in the current proof tree, along with the type + and the context of each variable. + + .. cmdv:: Show Match @ident + + This variant displays a template of the Gallina + ``match`` construct with a branch for each constructor of the type + :token:`ident` + + .. example:: + + .. coqtop:: all + + Show Match nat. + + .. exn:: Unknown inductive type. + :undocumented: + + .. cmdv:: Show Universes + :name: Show Universes + + It displays the set of all universe constraints and + its normalized form at the current stage of the proof, useful for + debugging universe inconsistencies. + + +.. cmd:: Guarded + + Some tactics (e.g. :tacn:`refine`) allow to build proofs using + fixpoint or co-fixpoint constructions. Due to the incremental nature + of interactive proof construction, the check of the termination (or + guardedness) of the recursive calls in the fixpoint or cofixpoint + constructions is postponed to the time of the completion of the proof. + + The command :cmd:`Guarded` allows checking if the guard condition for + fixpoint and cofixpoint is violated at some time of the construction + of the proof without having to wait the completion of the proof. + +.. _showing_diffs: + +Showing differences between proof steps +--------------------------------------- + + +Coq can automatically highlight the differences between successive proof steps and between +values in some error messages. +For example, the following screenshots of CoqIDE and coqtop show the application +of the same :tacn:`intros` tactic. The tactic creates two new hypotheses, highlighted in green. +The conclusion is entirely in pale green because although it’s changed, no tokens were added +to it. The second screenshot uses the "removed" option, so it shows the conclusion a +second time with the old text, with deletions marked in red. Also, since the hypotheses are +new, no line of old text is shown for them. + +.. comment screenshot produced with: + Inductive ev : nat -> Prop := + | ev_0 : ev 0 + | ev_SS : forall n : nat, ev n -> ev (S (S n)). + + Fixpoint double (n:nat) := + match n with + | O => O + | S n' => S (S (double n')) + end. + + Goal forall n, ev n -> exists k, n = double k. + intros n E. + +.. + + .. image:: ../_static/diffs-coqide-on.png + :alt: |CoqIDE| with Set Diffs on + +.. + + .. image:: ../_static/diffs-coqide-removed.png + :alt: |CoqIDE| with Set Diffs removed + +.. + + .. image:: ../_static/diffs-coqtop-on3.png + :alt: coqtop with Set Diffs on + +This image shows an error message with diff highlighting in CoqIDE: + +.. + + .. image:: ../_static/diffs-error-message.png + :alt: |CoqIDE| error message with diffs + +How to enable diffs +``````````````````` + +.. opt:: Diffs %( "on" %| "off" %| "removed" %) + :name: Diffs + + The “on” setting highlights added tokens in green, while the “removed” setting + additionally reprints items with removed tokens in red. Unchanged tokens in + modified items are shown with pale green or red. Diffs in error messages + use red and green for the compared values; they appear regardless of the setting. + (Colors are user-configurable.) + +For coqtop, showing diffs can be enabled when starting coqtop with the +``-diffs on|off|removed`` command-line option or by setting the :opt:`Diffs` option +within Coq. You will need to provide the ``-color on|auto`` command-line option when +you start coqtop in either case. + +Colors for coqtop can be configured by setting the ``COQ_COLORS`` environment +variable. See section :ref:`customization-by-environment-variables`. Diffs +use the tags ``diff.added``, ``diff.added.bg``, ``diff.removed`` and ``diff.removed.bg``. + +In CoqIDE, diffs should be enabled from the ``View`` menu. Don’t use the ``Set Diffs`` +command in CoqIDE. You can change the background colors shown for diffs from the +``Edit | Preferences | Tags`` panel by changing the settings for the ``diff.added``, +``diff.added.bg``, ``diff.removed`` and ``diff.removed.bg`` tags. This panel also +lets you control other attributes of the highlights, such as the foreground +color, bold, italic, underline and strikeout. + +Note: As of this writing (August 2018), Proof General will need minor changes +to be able to show diffs correctly. We hope it will support this feature soon. +See https://github.com/ProofGeneral/PG/issues/381 for the current status. + +How diffs are calculated +```````````````````````` + +Diffs are calculated as follows: + +1. Select the old proof state to compare to, which is the proof state before + the last tactic that changed the proof. Changes that only affect the view + of the proof, such as ``all: swap 1 2``, are ignored. + +2. For each goal in the new proof state, determine what old goal to compare + it to—the one it is derived from or is the same as. Match the hypotheses by + name (order is ignored), handling compacted items specially. + +3. For each hypothesis and conclusion (the “items”) in each goal, pass + them as strings to the lexer to break them into tokens. Then apply the + Myers diff algorithm :cite:`Myers` on the tokens and add appropriate highlighting. + +Notes: + +* Aside from the highlights, output for the "on" option should be identical + to the undiffed output. +* Goals completed in the last proof step will not be shown even with the + "removed" setting. + +.. comment The following screenshots show diffs working with multiple goals and with compacted + hypotheses. In the first one, notice that the goal ``P 1`` is not highlighted at + all after the split because it has not changed. + + .. todo: Use this script and remove the screenshots when COQ_COLORS + works for coqtop in sphinx + .. coqtop:: none + + Set Diffs "on". + Parameter P : nat -> Prop. + Goal P 1 /\ P 2 /\ P 3. + + .. coqtop:: out + + split. + + .. coqtop:: all abort + + 2: split. + + .. + + .. coqtop:: none + + Set Diffs "on". + Goal forall n m : nat, n + m = m + n. + Set Diffs "on". + + .. coqtop:: out + + intros n. + + .. coqtop:: all abort + + intros m. + +This screen shot shows the result of applying a :tacn:`split` tactic that replaces one goal +with 2 goals. Notice that the goal ``P 1`` is not highlighted at all after +the split because it has not changed. + +.. + + .. image:: ../_static/diffs-coqide-multigoal.png + :alt: coqide with Set Diffs on with multiple goals + +This is how diffs may appear after applying a :tacn:`intro` tactic that results +in compacted hypotheses: + +.. + + .. image:: ../_static/diffs-coqide-compacted.png + :alt: coqide with Set Diffs on with compacted hyptotheses + +Controlling the effect of proof editing commands +------------------------------------------------ + + +.. opt:: Hyps Limit @num + :name: Hyps Limit + + This option controls the maximum number of hypotheses displayed in goals + after the application of a tactic. All the hypotheses remain usable + in the proof development. + When unset, it goes back to the default mode which is to print all + available hypotheses. + + +.. flag:: Nested Proofs Allowed + + When turned on (it is off by default), this option enables support for nested + proofs: a new assertion command can be inserted before the current proof is + finished, in which case Coq will temporarily switch to the proof of this + *nested lemma*. When the proof of the nested lemma is finished (with :cmd:`Qed` + or :cmd:`Defined`), its statement will be made available (as if it had been + proved before starting the previous proof) and Coq will switch back to the + proof of the previous assertion. + + +Controlling memory usage +------------------------ + +When experiencing high memory usage the following commands can be used +to force |Coq| to optimize some of its internal data structures. + + +.. cmd:: Optimize Proof + + This command forces |Coq| to shrink the data structure used to represent + the ongoing proof. + + +.. cmd:: Optimize Heap + + This command forces the |OCaml| runtime to perform a heap compaction. + This is in general an expensive operation. + See: `OCaml Gc <http://caml.inria.fr/pub/docs/manual-ocaml/libref/Gc.html#VALcompact>`_ + There is also an analogous tactic :tacn:`optimize_heap`. diff --git a/doc/sphinx/proof-engine/ssreflect-proof-language.rst b/doc/sphinx/proof-engine/ssreflect-proof-language.rst new file mode 100644 index 0000000000..b240cef40c --- /dev/null +++ b/doc/sphinx/proof-engine/ssreflect-proof-language.rst @@ -0,0 +1,5508 @@ +.. _thessreflectprooflanguage: + +------------------------------ + The |SSR| proof language +------------------------------ + +:Authors: Georges Gonthier, Assia Mahboubi, Enrico Tassi + + +Introduction +------------ + +This chapter describes a set of tactics known as |SSR| originally +designed to provide support for the so-called *small scale reflection* +proof methodology. Despite the original purpose this set of tactic is +of general interest and is available in |Coq| starting from version 8.7. + +|SSR| was developed independently of the tactics described in +Chapter :ref:`tactics`. Indeed the scope of the tactics part of |SSR| largely +overlaps with the standard set of tactics. Eventually the overlap will +be reduced in future releases of |Coq|. + +Proofs written in |SSR| typically look quite different from the +ones written using only tactics as per Chapter :ref:`tactics`. We try to +summarise here the most “visible” ones in order to help the reader +already accustomed to the tactics described in Chapter :ref:`tactics` to read +this chapter. + +The first difference between the tactics described in this chapter and the +tactics described in Chapter :ref:`tactics` is the way hypotheses are managed +(we call this *bookkeeping*). In Chapter :ref:`tactics` the most common +approach is to avoid moving explicitly hypotheses back and forth between the +context and the conclusion of the goal. On the contrary in |SSR| all +bookkeeping is performed on the conclusion of the goal, using for that +purpose a couple of syntactic constructions behaving similar to tacticals +(and often named as such in this chapter). The ``:`` tactical moves hypotheses +from the context to the conclusion, while ``=>`` moves hypotheses from the +conclusion to the context, and ``in`` moves back and forth a hypothesis from the +context to the conclusion for the time of applying an action to it. + +While naming hypotheses is commonly done by means of an ``as`` clause in the +basic model of Chapter :ref:`tactics`, it is here to ``=>`` that this task is +devoted. Tactics frequently leave new assumptions in the conclusion, and are +often followed by ``=>`` to explicitly name them. While generalizing the +goal is normally not explicitly needed in Chapter :ref:`tactics`, it is an +explicit operation performed by ``:``. + +.. seealso:: :ref:`bookkeeping_ssr` + +Beside the difference of bookkeeping model, this chapter includes +specific tactics which have no explicit counterpart in Chapter :ref:`tactics` +such as tactics to mix forward steps and generalizations as +:tacn:`generally have` or :tacn:`without loss`. + +|SSR| adopts the point of view that rewriting, definition +expansion and partial evaluation participate all to a same concept of +rewriting a goal in a larger sense. As such, all these functionalities +are provided by the :tacn:`rewrite <rewrite (ssreflect)>` tactic. + +|SSR| includes a little language of patterns to select subterms in +tactics or tacticals where it matters. Its most notable application is +in the :tacn:`rewrite <rewrite (ssreflect)>` tactic, where patterns are +used to specify where the rewriting step has to take place. + +Finally, |SSR| supports so-called reflection steps, typically +allowing to switch back and forth between the computational view and +logical view of a concept. + +To conclude it is worth mentioning that |SSR| tactics can be mixed +with non |SSR| tactics in the same proof, or in the same Ltac +expression. The few exceptions to this statement are described in +section :ref:`compatibility_issues_ssr`. + + +Acknowledgments +~~~~~~~~~~~~~~~ + +The authors would like to thank Frédéric Blanqui, François Pottier and +Laurence Rideau for their comments and suggestions. + + +Usage +----- + + +Getting started +~~~~~~~~~~~~~~~ + +To be available, the tactics presented in this manual need the +following minimal set of libraries to be loaded: ``ssreflect.v``, +``ssrfun.v`` and ``ssrbool.v``. +Moreover, these tactics come with a methodology +specific to the authors of |SSR| and which requires a few options +to be set in a different way than in their default way. All in all, +this corresponds to working in the following context: + +.. coqtop:: in + + From Coq Require Import ssreflect ssrfun ssrbool. + Set Implicit Arguments. + Unset Strict Implicit. + Unset Printing Implicit Defensive. + +.. seealso:: + :flag:`Implicit Arguments`, :flag:`Strict Implicit`, + :flag:`Printing Implicit Defensive` + +.. _compatibility_issues_ssr: + + +Compatibility issues +~~~~~~~~~~~~~~~~~~~~ + +Requiring the above modules creates an environment which is mostly +compatible with the rest of |Coq|, up to a few discrepancies: + + ++ New keywords (``is``) might clash with variable, constant, tactic or + tactical names, or with quasi-keywords in tactic or vernacular + notations. ++ New tactic(al)s names (:tacn:`last`, :tacn:`done`, :tacn:`have`, :tacn:`suffices`, + :tacn:`suff`, :tacn:`without loss`, :tacn:`wlog`, :tacn:`congr`, :tacn:`unlock`) + might clash with user tactic names. ++ Identifiers with both leading and trailing ``_``, such as ``_x_``, are + reserved by |SSR| and cannot appear in scripts. ++ The extensions to the :tacn:`rewrite` tactic are partly incompatible with those + available in current versions of |Coq|; in particular: ``rewrite .. in + (type of k)`` or ``rewrite .. in *`` or any other variant of :tacn:`rewrite` + will not work, and the |SSR| syntax and semantics for occurrence selection + and rule chaining is different. Use an explicit rewrite direction + (``rewrite <- …`` or ``rewrite -> …``) to access the |Coq| rewrite tactic. ++ New symbols (``//``, ``/=``, ``//=``) might clash with adjacent + existing symbols. + This can be avoided by inserting white spaces. ++ New constant and theorem names might clash with the user theory. + This can be avoided by not importing all of |SSR|: + + .. coqtop:: in + + From Coq Require ssreflect. + Import ssreflect.SsrSyntax. + + Note that the full + syntax of |SSR|’s rewrite and reserved identifiers are enabled + only if the ssreflect module has been required and if ``SsrSyntax`` has + been imported. Thus a file that requires (without importing) ``ssreflect`` + and imports ``SsrSyntax``, can be required and imported without + automatically enabling |SSR|’s extended rewrite syntax and + reserved identifiers. ++ Some user notations (in particular, defining an infix ``;``) might + interfere with the "open term", parenthesis free, syntax of tactics + such as have, set and pose. ++ The generalization of if statements to non-Boolean conditions is turned off + by |SSR|, because it is mostly subsumed by Coercion to ``bool`` of the + ``sumXXX`` types (declared in ``ssrfun.v``) and the + :n:`if @term is @pattern then @term else @term` construct + (see :ref:`pattern_conditional_ssr`). To use the + generalized form, turn off the |SSR| Boolean ``if`` notation using the command: + ``Close Scope boolean_if_scope``. ++ The following flags can be unset to make |SSR| more compatible with + parts of Coq: + +.. flag:: SsrRewrite + + Controls whether the incompatible rewrite syntax is enabled (the default). + Disabling the flag makes the syntax compatible with other parts of Coq. + +.. flag:: SsrIdents + + Controls whether tactics can refer to |SSR|-generated variables that are + in the form _xxx_. Scripts with explicit references to such variables + are fragile; they are prone to failure if the proof is later modified or + if the details of variable name generation change in future releases of Coq. + + The default is on, which gives an error message when the user tries to + create such identifiers. Disabling the flag generates a warning instead, + increasing compatibility with other parts of Coq. + +|Gallina| extensions +-------------------- + +Small-scale reflection makes an extensive use of the programming +subset of |Gallina|, |Coq|’s logical specification language. This subset +is quite suited to the description of functions on representations, +because it closely follows the well-established design of the ML +programming language. The |SSR| extension provides three additions +to |Gallina|, for pattern assignment, pattern testing, and polymorphism; +these mitigate minor but annoying discrepancies between |Gallina| and +ML. + + +Pattern assignment +~~~~~~~~~~~~~~~~~~ + +The |SSR| extension provides the following construct for +irrefutable pattern matching, that is, destructuring assignment: + +.. prodn:: + term += let: @pattern := @term in @term + +Note the colon ``:`` after the ``let`` keyword, which avoids any ambiguity +with a function definition or |Coq|’s basic destructuring let. The let: +construct differs from the latter in that + + ++ The pattern can be nested (deep pattern matching), in particular, + this allows expression of the form: + +.. coqdoc:: + + let: exist (x, y) p_xy := Hp in … . + ++ The destructured constructor is explicitly given in the pattern, and + is used for type inference. + + .. example:: + + .. coqtop:: reset none + + From Coq Require Import ssreflect. + Set Implicit Arguments. + Unset Strict Implicit. + Unset Printing Implicit Defensive. + + .. coqtop:: all + + Definition f u := let: (m, n) := u in m + n. + Check f. + + Using :g:`let:` Coq infers a type for :g:`f`, + whereas with a usual ``let`` the same term requires an extra type + annotation in order to type check. + + .. coqtop:: reset all + + Fail Definition f u := let (m, n) := u in m + n. + + +The ``let:`` construct is just (more legible) notation for the primitive +|Gallina| expression :n:`match @term with @pattern => @term end`. + +The |SSR| destructuring assignment supports all the dependent +match annotations; the full syntax is + +.. prodn:: + term += let: @pattern {? as @ident} {? in @pattern} := @term {? return @term} in @term + +where the second :token:`pattern` and the second :token:`term` are *types*. + +When the ``as`` and ``return`` keywords are both present, then :token:`ident` is bound +in both the second :token:`pattern` and the second :token:`term`; variables +in the optional type :token:`pattern` are bound only in the second term, and +other variables in the first :token:`pattern` are bound only in the third +:token:`term`, however. + + +.. _pattern_conditional_ssr: + +Pattern conditional +~~~~~~~~~~~~~~~~~~~ + +The following construct can be used for a refutable pattern matching, +that is, pattern testing: + +.. prodn:: + term += if @term is @pattern then @term else @term + +Although this construct is not strictly ML (it does exist in variants +such as the pattern calculus or the ρ-calculus), it turns out to be +very convenient for writing functions on representations, because most +such functions manipulate simple data types such as Peano integers, +options, lists, or binary trees, and the pattern conditional above is +almost always the right construct for analyzing such simple types. For +example, the null and all list function(al)s can be defined as follows: + +.. example:: + + .. coqtop:: reset none + + From Coq Require Import ssreflect. + Set Implicit Arguments. + Unset Strict Implicit. + Unset Printing Implicit Defensive. + Section Test. + + .. coqtop:: all + + Variable d: Set. + Fixpoint null (s : list d) := + if s is nil then true else false. + Variable a : d -> bool. + Fixpoint all (s : list d) : bool := + if s is cons x s' then a x && all s' else true. + +The pattern conditional also provides a notation for destructuring +assignment with a refutable pattern, adapted to the pure functional +setting of |Gallina|, which lacks a ``Match_Failure`` exception. + +Like ``let:`` above, the ``if…is`` construct is just (more legible) notation +for the primitive |Gallina| expression +:n:`match @term with @pattern => @term | _ => @term end`. + +Similarly, it will always be displayed as the expansion of this form +in terms of primitive match expressions (where the default expression +may be replicated). + +Explicit pattern testing also largely subsumes the generalization of +the ``if`` construct to all binary data types; compare +:n:`if @term is inl _ then @term else @term` and +:n:`if @term then @term else @term`. + +The latter appears to be marginally shorter, but it is quite +ambiguous, and indeed often requires an explicit annotation +``(term : {_} + {_})`` to type check, which evens the character count. + +Therefore, |SSR| restricts by default the condition of a plain if +construct to the standard ``bool`` type; this avoids spurious type +annotations. + +.. example:: + + .. coqtop:: all + + Definition orb b1 b2 := if b1 then true else b2. + +As pointed out in section :ref:`compatibility_issues_ssr`, +this restriction can be removed with +the command: + +``Close Scope boolean_if_scope.`` + +Like ``let:`` above, the ``if-is-then-else`` +construct supports +the dependent match annotations: + +.. prodn:: + term += if @term is @pattern as @ident in @pattern return @term then @term else @term + +As in ``let:`` the variable :token:`ident` (and those in the type pattern) +are bound in the second :token:`term`; :token:`ident` is also bound in the +third :token:`term` (but not in the fourth :token:`term`), while the +variables in the first :token:`pattern` are bound only in the third +:token:`term`. + +Another variant allows to treat the ``else`` case first: + +.. prodn:: + term += if @term isn't @pattern then @term else @term + +Note that :token:`pattern` eventually binds variables in the third +:token:`term` and not in the second :token:`term`. + +.. _parametric_polymorphism_ssr: + +Parametric polymorphism +~~~~~~~~~~~~~~~~~~~~~~~ + +Unlike ML, polymorphism in core |Gallina| is explicit: the type +parameters of polymorphic functions must be declared explicitly, and +supplied at each point of use. However, |Coq| provides two features to +suppress redundant parameters: + + ++ Sections are used to provide (possibly implicit) parameters for a + set of definitions. ++ Implicit arguments declarations are used to tell |Coq| to use type + inference to deduce some parameters from the context at each point of + call. + + +The combination of these features provides a fairly good emulation of +ML-style polymorphism, but unfortunately this emulation breaks down +for higher-order programming. Implicit arguments are indeed not +inferred at all points of use, but only at points of call, leading to +expressions such as + +.. example:: + + .. coqtop:: reset none + + From Coq Require Import ssreflect. + Set Implicit Arguments. + Unset Strict Implicit. + Unset Printing Implicit Defensive. + Section Test. + Variable T : Type. + Variable null : forall T : Type, T -> bool. + Variable all : (T -> bool) -> list T -> bool. + + .. coqtop:: all + + Definition all_null (s : list T) := all (@null T) s. + +Unfortunately, such higher-order expressions are quite frequent in +representation functions, especially those which use |Coq|'s +``Structures`` to emulate Haskell typeclasses. + +Therefore, |SSR| provides a variant of |Coq|’s implicit argument +declaration, which causes |Coq| to fill in some implicit parameters at +each point of use, e.g., the above definition can be written: + +.. example:: + + .. coqtop:: reset none + + From Coq Require Import ssreflect. + Set Implicit Arguments. + Unset Strict Implicit. + Unset Printing Implicit Defensive. + Section Test. + Variable T : Type. + Variable null : forall T : Type, T -> bool. + Variable all : (T -> bool) -> list T -> bool. + + + .. coqtop:: all + + Prenex Implicits null. + Definition all_null (s : list T) := all null s. + +Better yet, it can be omitted entirely, since :g:`all_null s` isn’t much of +an improvement over :g:`all null s`. + +The syntax of the new declaration is + +.. cmd:: Prenex Implicits {+ @ident__i} + + This command checks that each :n:`@ident__i` is the name of a functional + constant, whose implicit arguments are prenex, i.e., the first + :math:`n_i > 0` arguments of :n:`@ident__i` are implicit; then it assigns + ``Maximal Implicit`` status to these arguments. + + As these prenex implicit arguments are ubiquitous and have often large + display strings, it is strongly recommended to change the default + display settings of |Coq| so that they are not printed (except after + a ``Set Printing All`` command). All |SSR| library files thus start + with the incantation + + .. coqdoc:: + + Set Implicit Arguments. + Unset Strict Implicit. + Unset Printing Implicit Defensive. + + +Anonymous arguments +~~~~~~~~~~~~~~~~~~~ + +When in a definition, the type of a certain argument is mandatory, but +not its name, one usually uses “arrow” abstractions for prenex +arguments, or the ``(_ : term)`` syntax for inner arguments. In |SSR|, +the latter can be replaced by the open syntax ``of term`` or +(equivalently) ``& term``, which are both syntactically equivalent to a +``(_ : term)`` expression. This feature almost behaves as the +following extension of the binder syntax: + +.. prodn:: + binder += & @term | of @term + +Caveat: ``& T`` and ``of T`` abbreviations have to appear at the end +of a binder list. For instance, the usual two-constructor polymorphic +type list, i.e. the one of the standard ``List`` library, can be +defined by the following declaration: + +.. example:: + + .. coqtop:: reset none + + From Coq Require Import ssreflect. + Set Implicit Arguments. + Unset Strict Implicit. + Unset Printing Implicit Defensive. + + .. coqtop:: all + + Inductive list (A : Type) : Type := nil | cons of A & list A. + + +Wildcards +~~~~~~~~~ + +The terms passed as arguments to |SSR| tactics can contain +*holes*, materialized by wildcards ``_``. Since |SSR| allows a more +powerful form of type inference for these arguments, it enhances the +possibilities of using such wildcards. These holes are in particular +used as a convenient shorthand for abstractions, especially in local +definitions or type expressions. + +Wildcards may be interpreted as abstractions (see for example sections +:ref:`definitions_ssr` and ref:`structure_ssr`), or their content can be +inferred from the whole context of the goal (see for example section +:ref:`abbreviations_ssr`). + + +.. _definitions_ssr: + +Definitions +~~~~~~~~~~~ + +.. tacn:: pose + :name: pose (ssreflect) + + This tactic allows to add a defined constant to a proof context. + |SSR| generalizes this tactic in several ways. In particular, the + |SSR| pose tactic supports *open syntax*: the body of the + definition does not need surrounding parentheses. For instance: + +.. coqdoc:: + + pose t := x + y. + +is a valid tactic expression. + +The pose tactic is also improved for the local definition of higher +order terms. Local definitions of functions can use the same syntax as +global ones. +For example, the tactic :tacn:`pose <pose (ssreflect)>` supoprts parameters: + +.. example:: + + .. coqtop:: reset none + + From Coq Require Import ssreflect. + Set Implicit Arguments. + Unset Strict Implicit. + Unset Printing Implicit Defensive. + + .. coqtop:: all + + Lemma test : True. + pose f x y := x + y. + +The |SSR| pose tactic also supports (co)fixpoints, by providing +the local counterpart of the ``Fixpoint f := …`` and ``CoFixpoint f := …`` +constructs. For instance, the following tactic: + +.. coqdoc:: + + pose fix f (x y : nat) {struct x} : nat := + if x is S p then S (f p y) else 0. + +defines a local fixpoint ``f``, which mimics the standard plus operation +on natural numbers. + +Similarly, local cofixpoints can be defined by a tactic of the form: + +.. coqdoc:: + + pose cofix f (arg : T) := … . + +The possibility to include wildcards in the body of the definitions +offers a smooth way of defining local abstractions. The type of +“holes” is guessed by type inference, and the holes are abstracted. +For instance the tactic: + +.. coqdoc:: + + pose f := _ + 1. + +is shorthand for: + +.. coqdoc:: + + pose f n := n + 1. + +When the local definition of a function involves both arguments and +holes, hole abstractions appear first. For instance, the tactic: + +.. coqdoc:: + + pose f x := x + _. + +is shorthand for: + +.. coqdoc:: + + pose f n x := x + n. + +The interaction of the pose tactic with the interpretation of implicit +arguments results in a powerful and concise syntax for local +definitions involving dependent types. For instance, the tactic: + +.. coqdoc:: + + pose f x y := (x, y). + +adds to the context the local definition: + +.. coqdoc:: + + pose f (Tx Ty : Type) (x : Tx) (y : Ty) := (x, y). + +The generalization of wildcards makes the use of the pose tactic +resemble ML-like definitions of polymorphic functions. + + +.. _abbreviations_ssr: + + +Abbreviations +~~~~~~~~~~~~~ + +.. tacn:: set @ident {? : @term } := {? @occ_switch } @term + :name: set (ssreflect) + + The |SSR| ``set`` tactic performs abbreviations: it introduces a + defined constant for a subterm appearing in the goal and/or in the + context. + + |SSR| extends the :tacn:`set` tactic by supplying: + + + an open syntax, similarly to the :tacn:`pose (ssreflect)` tactic; + + a more aggressive matching algorithm; + + an improved interpretation of wildcards, taking advantage of the + matching algorithm; + + an improved occurrence selection mechanism allowing to abstract only + selected occurrences of a term. + +.. prodn:: + occ_switch ::= { {? + %| - } {* @num } } + +where: + ++ :token:`ident` is a fresh identifier chosen by the user. ++ term 1 is an optional type annotation. The type annotation term 1 + can be given in open syntax (no surrounding parentheses). If no + :token:`occ_switch` (described hereafter) is present, + it is also the case for the second :token:`term`. + On the other hand, in presence of :token:`occ_switch`, parentheses + surrounding the second :token:`term` are mandatory. ++ In the occurrence switch :token:`occ_switch`, if the first element of the + list is a natural, this element should be a number, and not an Ltac + variable. The empty list ``{}`` is not interpreted as a valid occurrence + switch, it is rather used as a flag to signal the intent of the user to + clear the name following it (see :ref:`ssr_rewrite_occ_switch` and + :ref:`introduction_ssr`) + +The tactic: + +.. example:: + + .. coqtop:: reset none + + From Coq Require Import ssreflect. + Set Implicit Arguments. + Unset Strict Implicit. + Unset Printing Implicit Defensive. + Axiom f : nat -> nat. + + .. coqtop:: all + + Lemma test x : f x + f x = f x. + set t := f _. + + .. coqtop:: all restart + + set t := {2}(f _). + + +The type annotation may contain wildcards, which will be filled +with the appropriate value by the matching process. + +The tactic first tries to find a subterm of the goal matching +the second :token:`term` +(and its type), and stops at the first subterm it finds. Then +the occurrences of this subterm selected by the optional :token:`occ_switch` +are replaced by :token:`ident` and a definition :n:`@ident := @term` +is added to the +context. If no :token:`occ_switch` is present, then all the occurrences are +abstracted. + + +Matching +```````` + +The matching algorithm compares a pattern :token:`term` with a subterm of the +goal by comparing their heads and then pairwise unifying their +arguments (modulo conversion). Head symbols match under the following +conditions: + + ++ If the head of :token:`term` is a constant, then it should be syntactically + equal to the head symbol of the subterm. ++ If this head is a projection of a canonical structure, then + canonical structure equations are used for the matching. ++ If the head of term is *not* a constant, the subterm should have the + same structure (λ abstraction,let…in structure …). ++ If the head of :token:`term` is a hole, the subterm should have at least as + many arguments as :token:`term`. + +.. example:: + + .. coqtop:: reset none + + From Coq Require Import ssreflect. + Set Implicit Arguments. + Unset Strict Implicit. + Unset Printing Implicit Defensive. + + .. coqtop:: all + + Lemma test (x y z : nat) : x + y = z. + set t := _ x. + ++ In the special case where ``term`` is of the form + ``(let f := t0 in f) t1 … tn`` , then the pattern ``term`` is treated + as ``(_ t1 … tn)``. For each + subterm in the goal having the form ``(A u1 … um)`` with m ≥ n, the + matching algorithm successively tries to find the largest partial + application ``(A u1 … uj)`` convertible to the head ``t0`` of ``term``. + + .. example:: + + .. coqtop:: reset none + + From Coq Require Import ssreflect. + Set Implicit Arguments. + Unset Strict Implicit. + Unset Printing Implicit Defensive. + + .. coqtop:: all + + Lemma test : (let f x y z := x + y + z in f 1) 2 3 = 6. + set t := (let g y z := S y + z in g) 2. + + The notation ``unkeyed`` defined in ``ssreflect.v`` is a shorthand for + the degenerate term ``let x := … in x``. + +Moreover: + ++ Multiple holes in ``term`` are treated as independent placeholders. + + .. example:: + + .. coqtop:: reset none + + From Coq Require Import ssreflect. + Set Implicit Arguments. + Unset Strict Implicit. + Unset Printing Implicit Defensive. + + .. coqtop:: all + + Lemma test x y z : x + y = z. + set t := _ + _. + ++ The type of the subterm matched should fit the type (possibly casted + by some type annotations) of the pattern ``term``. ++ The replacement of the subterm found by the instantiated pattern + should not capture variables. In the example above ``x`` is bound + and should not be captured. + + .. example:: + + .. coqtop:: reset none + + From Coq Require Import ssreflect. + Set Implicit Arguments. + Unset Strict Implicit. + Unset Printing Implicit Defensive. + + .. coqtop:: all + + Lemma test : forall x : nat, x + 1 = 0. + Fail set t := _ + 1. + ++ Typeclass inference should fill in any residual hole, but matching + should never assign a value to a global existential variable. + + +.. _occurrence_selection_ssr: + +Occurrence selection +```````````````````` + +|SSR| provides a generic syntax for the selection of occurrences +by their position indexes. These *occurrence switches* are shared by +all |SSR| tactics which require control on subterm selection like +rewriting, generalization, … + +An *occurrence switch* can be: + ++ A list natural numbers ``{+ n1 … nm}`` + of occurrences affected by the tactic. + + .. example:: + + .. coqtop:: reset none + + From Coq Require Import ssreflect. + Set Implicit Arguments. + Unset Strict Implicit. + Unset Printing Implicit Defensive. + Axiom f : nat -> nat. + + .. coqtop:: all + + Lemma test : f 2 + f 8 = f 2 + f 2. + set x := {+1 3}(f 2). + + Notice that some occurrences of a given term may be + hidden to the user, for example because of a notation. The vernacular + ``Set Printing All`` command displays all these hidden occurrences and + should be used to find the correct coding of the occurrences to be + selected [#1]_. + + .. example:: + + .. coqtop:: reset none + + From Coq Require Import ssreflect. + Set Implicit Arguments. + Unset Strict Implicit. + Unset Printing Implicit Defensive. + + .. coqtop:: all + + Notation "a < b":= (le (S a) b). + Lemma test x y : x < y -> S x < S y. + set t := S x. + ++ A list of natural numbers between ``{n1 … nm}``. + This is equivalent to the previous ``{+ n1 … nm}`` but the list + should start with a number, and not with an Ltac variable. ++ A list ``{- n1 … nm}`` of occurrences *not* to be affected by the + tactic. + + .. example:: + + .. coqtop:: reset none + + From Coq Require Import ssreflect. + Set Implicit Arguments. + Unset Strict Implicit. + Unset Printing Implicit Defensive. + Axiom f : nat -> nat. + + .. coqtop:: all + + Lemma test : f 2 + f 8 = f 2 + f 2. + set x := {-2}(f 2). + + + Note that, in this goal, it behaves like ``set x := {1 3}(f 2).`` ++ In particular, the switch ``{+}`` selects *all* the occurrences. This + switch is useful to turn off the default behavior of a tactic which + automatically clears some assumptions (see section :ref:`discharge_ssr` for + instance). ++ The switch ``{-}`` imposes that *no* occurrences of the term should be + affected by the tactic. The tactic: ``set x := {-}(f 2).`` leaves the goal + unchanged and adds the definition ``x := f 2`` to the context. This kind + of tactic may be used to take advantage of the power of the matching + algorithm in a local definition, instead of copying large terms by + hand. + +It is important to remember that matching *preceeds* occurrence +selection. + + .. example:: + + .. coqtop:: reset none + + From Coq Require Import ssreflect. + Set Implicit Arguments. + Unset Strict Implicit. + Unset Printing Implicit Defensive. + + .. coqtop:: all + + Lemma test x y z : x + y = x + y + z. + set a := {2}(_ + _). + +Hence, in the following goal, the same tactic fails since there is +only one occurrence of the selected term. + + .. example:: + + .. coqtop:: reset none + + From Coq Require Import ssreflect. + Set Implicit Arguments. + Unset Strict Implicit. + Unset Printing Implicit Defensive. + + .. coqtop:: all + + Lemma test x y z : (x + y) + (z + z) = z + z. + Fail set a := {2}(_ + _). + + +.. _basic_localization_ssr: + +Basic localization +~~~~~~~~~~~~~~~~~~ + +It is possible to define an abbreviation for a term appearing in the +context of a goal thanks to the ``in`` tactical. + +.. tacv:: set @ident := @term in {+ @ident} + + This variant of :tacn:`set (ssreflect)` introduces a defined constant + called :token:`ident` in the context, and folds it in + the context entries mentioned on the right hand side of ``in``. + The body of :token:`ident` is the first subterm matching these context + entries (taken in the given order). + + .. example:: + + .. coqtop:: reset none + + From Coq Require Import ssreflect. + + .. coqtop:: all + + Lemma test x t (Hx : x = 3) : x + t = 4. + set z := 3 in Hx. + +.. tacv:: set @ident := @term in {+ @ident} * + + This variant matches :token:`term` and then folds :token:`ident` similarly + in all the given context entries but also folds :token:`ident` in the goal. + + .. example:: + + .. coqtop:: reset none + + From Coq Require Import ssreflect. + + .. coqtop:: all + + Lemma test x t (Hx : x = 3) : x + t = 4. + set z := 3 in Hx * . + + Indeed, remember that 4 is just a notation for (S 3). + +The use of the ``in`` tactical is not limited to the localization of +abbreviations: for a complete description of the in tactical, see +section :ref:`bookkeeping_ssr` and :ref:`localization_ssr`. + + +.. _basic_tactics_ssr: + +Basic tactics +------------- + +A sizable fraction of proof scripts consists of steps that do not +"prove" anything new, but instead perform menial bookkeeping tasks +such as selecting the names of constants and assumptions or splitting +conjuncts. Although they are logically trivial, bookkeeping steps are +extremely important because they define the structure of the data-flow +of a proof script. This is especially true for reflection-based +proofs, which often involve large numbers of constants and +assumptions. Good bookkeeping consists in always explicitly declaring +(i.e., naming) all new constants and assumptions in the script, and +systematically pruning irrelevant constants and assumptions in the +context. This is essential in the context of an interactive +development environment (IDE), because it facilitates navigating the +proof, allowing to instantly "jump back" to the point at which a +questionable assumption was added, and to find relevant assumptions by +browsing the pruned context. While novice or casual |Coq| users may find +the automatic name selection feature convenient, the usage of such a +feature severely undermines the readability and maintainability of +proof scripts, much like automatic variable declaration in programming +languages. The |SSR| tactics are therefore designed to support +precise bookkeeping and to eliminate name generation heuristics. The +bookkeeping features of |SSR| are implemented as tacticals (or +pseudo-tacticals), shared across most |SSR| tactics, and thus form +the foundation of the |SSR| proof language. + + +.. _bookkeeping_ssr: + +Bookkeeping +~~~~~~~~~~~ + +During the course of a proof |Coq| always present the user with a +*sequent* whose general form is:: + + ci : Ti + … + dj := ej : Tj + … + Fk : Pk + … + ================= + forall (xl : Tl ) …, + let ym := bm in … in + Pn -> … -> C + +The *goal* to be proved appears below the double line; above the line +is the *context* of the sequent, a set of declarations of *constants* +``ci`` , *defined constants* d i , and *facts* ``Fk`` that can be used to +prove the goal (usually, ``Ti`` , ``Tj : Type`` and ``Pk : Prop``). +The various +kinds of declarations can come in any order. The top part of the +context consists of declarations produced by the Section +commands ``Variable``, ``Let``, and ``Hypothesis``. +This *section context* is never +affected by the |SSR| tactics: they only operate on the lower part +— the *proof context*. As in the figure above, the goal often +decomposes into a series of (universally) quantified *variables* +``(xl : Tl)``, local *definitions* +``let ym := bm in``, and *assumptions* +``P n ->``, +and a *conclusion* ``C`` (as in the context, variables, definitions, and +assumptions can appear in any order). The conclusion is what actually +needs to be proved — the rest of the goal can be seen as a part of the +proof context that happens to be “below the line”. + +However, although they are logically equivalent, there are fundamental +differences between constants and facts on the one hand, and variables +and assumptions on the others. Constants and facts are *unordered*, +but *named* explicitly in the proof text; variables and assumptions +are *ordered*, but *unnamed*: the display names of variables may +change at any time because of α-conversion. + +Similarly, basic deductive steps such as apply can only operate on the +goal because the |Gallina| terms that control their action (e.g., the +type of the lemma used by ``apply``) only provide unnamed bound variables. +[#2]_ Since the proof script can only refer directly to the context, it +must constantly shift declarations from the goal to the context and +conversely in between deductive steps. + +In |SSR| these moves are performed by two *tacticals* ``=>`` and +``:``, so that the bookkeeping required by a deductive step can be +directly associated to that step, and that tactics in an |SSR| +script correspond to actual logical steps in the proof rather than +merely shuffle facts. Still, some isolated bookkeeping is unavoidable, +such as naming variables and assumptions at the beginning of a +proof. |SSR| provides a specific ``move`` tactic for this purpose. + +Now ``move`` does essentially nothing: it is mostly a placeholder for +``=>`` and ``:``. The ``=>`` tactical moves variables, local definitions, +and assumptions to the context, while the ``:`` tactical moves facts and +constants to the goal. + +.. example:: + + For example, the proof of [#3]_ + + .. coqtop:: reset none + + From Coq Require Import ssreflect. + Set Implicit Arguments. + Unset Strict Implicit. + Unset Printing Implicit Defensive. + + .. coqtop:: all + + Lemma subnK : forall m n, n <= m -> m - n + n = m. + + might start with + + .. coqtop:: all + + move=> m n le_n_m. + + where move does nothing, but ``=> m n le_m_n`` changes + the variables and assumption of the goal in the constants + ``m n : nat`` and the fact ``le_n_m : n <= m``, thus exposing the + conclusion ``m - n + n = m``. + + The ``:`` tactical is the converse of ``=>``, indeed it removes facts and + constants from the context by turning them into variables and + assumptions. + + .. coqtop:: all + + move: m le_n_m. + + turns back ``m`` and ``le_m_n`` into a variable and an assumption, + removing them from the proof context, and changing the goal to + ``forall m, n <= m -> m - n + n = m`` + which can be proved by induction on ``n`` using ``elim: n``. + +Because they are tacticals, ``:`` and ``=>`` can be combined, as in + +.. coqdoc:: + + move: m le_n_m => p le_n_p. + +simultaneously renames ``m`` and ``le_m_n`` into ``p`` and ``le_n_p``, +respectively, by first turning them into unnamed variables, then +turning these variables back into constants and facts. + +Furthermore, |SSR| redefines the basic |Coq| tactics ``case``, ``elim``, +and ``apply`` so that they can take better advantage of +``:`` and ``=>``. In there +|SSR| variants, these tactic operate on the first variable or +constant of the goal and they do not use or change the proof context. +The ``:`` tactical is used to operate on an element in the context. + +.. example:: + + For instance the proof of ``subnK`` could continue with ``elim: n``. + Instead of ``elim n`` (note, no colon), this has the advantage of + removing n from the context. Better yet, this ``elim`` can be combined + with previous move and with the branching version of the ``=>`` tactical + (described in :ref:`introduction_ssr`), + to encapsulate the inductive step in a single + command: + + .. coqtop:: reset none + + From Coq Require Import ssreflect. + Set Implicit Arguments. + Unset Strict Implicit. + Unset Printing Implicit Defensive. + + .. coqtop:: all + + Lemma subnK : forall m n, n <= m -> m - n + n = m. + move=> m n le_n_m. + elim: n m le_n_m => [|n IHn] m => [_ | lt_n_m]. + + which breaks down the proof into two subgoals, the second one + having in its context + ``lt_n_m : S n <= m`` and + ``IHn : forall m, n <= m -> m - n + n = m``. + +The ``:`` and ``=>`` tacticals can be explained very simply if one views +the goal as a stack of variables and assumptions piled on a conclusion: + ++ ``tactic : a b c`` pushes the context constants ``a``, ``b``, ``c`` as goal + variables *before* performing tactic. ++ ``tactic => a b c`` pops the top three goal variables as context + constants ``a``, ``b``, ``c``, *after* tactic has been performed. + +These pushes and pops do not need to balance out as in the examples +above, so ``move: m le_n_m => p`` +would rename ``m`` into ``p``, but leave an extra assumption ``n <= p`` +in the goal. + +Basic tactics like apply and elim can also be used without the ’:’ +tactical: for example we can directly start a proof of ``subnK`` by +induction on the top variable ``m`` with + +.. coqdoc:: + + elim=> [|m IHm] n le_n. + +The general form of the localization tactical in is also best +explained in terms of the goal stack:: + + tactic in a H1 H2 *. + +is basically equivalent to + +.. coqdoc:: + + move: a H1 H2; tactic => a H1 H2. + + +with two differences: the in tactical will preserve the body of a ifa +is a defined constant, and if the ``*`` is omitted it will use a +temporary abbreviation to hide the statement of the goal from +``tactic``. + +The general form of the in tactical can be used directly with the +``move``, ``case`` and ``elim`` tactics, so that one can write + +.. coqdoc:: + + elim: n => [|n IHn] in m le_n_m *. + +instead of + +.. coqdoc:: + + elim: n m le_n_m => [|n IHn] m le_n_m. + +This is quite useful for inductive proofs that involve many facts. + +See section :ref:`localization_ssr` for +the general syntax and presentation of the in +tactical. + + +.. _the_defective_tactics_ssr: + +The defective tactics +~~~~~~~~~~~~~~~~~~~~~ + +In this section we briefly present the three basic tactics performing +context manipulations and the main backward chaining tool. + + +The move tactic. +```````````````` + +.. tacn:: move + :name: move + + This tactic, in its defective form, behaves like the :tacn:`hnf` tactic. + + .. example:: + + .. coqtop:: reset all + + Require Import ssreflect. + Goal not False. + move. + + More precisely, the :tacn:`move` tactic inspects the goal and does nothing + (:tacn:`idtac`) if an introduction step is possible, i.e. if the goal is a + product or a ``let … in``, and performs :tacn:`hnf` otherwise. + + Of course this tactic is most often used in combination with the bookkeeping + tacticals (see section :ref:`introduction_ssr` and :ref:`discharge_ssr`). + These combinations mostly subsume the :tacn:`intros`, :tacn:`generalize`, + :tacn:`revert`, :tacn:`rename`, :tacn:`clear` and :tacn:`pattern` tactics. + + +The case tactic +``````````````` + +.. tacn:: case + :name: case (ssreflect) + + This tactic performs *primitive case analysis* on (co)inductive + types; specifically, it destructs the top variable or assumption of + the goal, exposing its constructor(s) and its arguments, as well as + setting the value of its type family indices if it belongs to a type + family (see section :ref:`type_families_ssr`). + + The |SSR| case tactic has a special behavior on equalities. If the + top assumption of the goal is an equality, the case tactic “destructs” + it as a set of equalities between the constructor arguments of its + left and right hand sides, as per the tactic injection. For example, + ``case`` changes the goal:: + + (x, y) = (1, 2) -> G. + + into:: + + x = 1 -> y = 2 -> G. + + Note also that the case of |SSR| performs :g:`False` elimination, even + if no branch is generated by this case operation. Hence the tactic + :tacn:`case` on a goal of the form :g:`False -> G` will succeed and + prove the goal. + + +The elim tactic +``````````````` + +.. tacn:: elim + :name: elim (ssreflect) + + This tactic performs inductive elimination on inductive types. In its + defective form, the tactic performs inductive elimination on a goal whose + top assumption has an inductive type. + + .. example:: + + .. coqtop:: reset none + + From Coq Require Import ssreflect. + Set Implicit Arguments. + Unset Strict Implicit. + Unset Printing Implicit Defensive. + + .. coqtop:: all + + Lemma test m : forall n : nat, m <= n. + elim. + + +.. _apply_ssr: + +The apply tactic +```````````````` + +.. tacn:: apply {? @term } + :name: apply (ssreflect) + + This is the main backward chaining tactic of the proof system. + It takes as argument any :token:`term` and applies it to the goal. + Assumptions in the type of :token:`term` that don’t directly match the goal + may generate one or more subgoals. + + In its defective form, this tactic is a synonym for:: + + intro top; first [refine top | refine (top _) | refine (top _ _) | …]; clear top. + + where :g:`top` is a fresh name, and the sequence of :tacn:`refine` tactics + tries to catch the appropriate number of wildcards to be inserted. Note that + this use of the :tacn:`refine` tactic implies that the tactic tries to match + the goal up to expansion of constants and evaluation of subterms. + +:tacn:`apply (ssreflect)` has a special behavior on goals containing +existential metavariables of sort :g:`Prop`. + +.. example:: + + .. coqtop:: reset none + + From Coq Require Import ssreflect. + Set Implicit Arguments. + Unset Strict Implicit. + Unset Printing Implicit Defensive. + Axiom lt_trans : forall a b c, a < b -> b < c -> a < c. + + .. coqtop:: all + + Lemma test : forall y, 1 < y -> y < 2 -> exists x : { n | n < 3 }, 0 < proj1_sig x. + move=> y y_gt1 y_lt2; apply: (ex_intro _ (exist _ y _)). + by apply: lt_trans y_lt2 _. + by move=> y_lt3; apply: lt_trans y_gt1. + + Note that the last ``_`` of the tactic + ``apply: (ex_intro _ (exist _ y _))`` + represents a proof that ``y < 3``. Instead of generating the goal:: + + 0 < proj1_sig (exist (fun n : nat => n < 3) y ?Goal). + + the system tries to prove ``y < 3`` calling the trivial tactic. + If it succeeds, let’s say because the context contains + ``H : y < 3``, then the + system generates the following goal:: + + 0 < proj1_sig (exist (fun n => n < 3) y H). + + Otherwise the missing proof is considered to be irrelevant, and is + thus discharged generating the two goals shown above. + + Last, the user can replace the trivial tactic by defining an Ltac + expression named ``ssrautoprop``. + + +.. _discharge_ssr: + +Discharge +~~~~~~~~~ + +The general syntax of the discharging tactical ``:`` is: + +.. tacn:: @tactic {? @ident } : {+ @d_item } {? @clear_switch } + :name: ... : ... (ssreflect) + :undocumented: + +.. prodn:: + d_item ::= {? @occ_switch %| @clear_switch } @term +.. prodn:: + clear_switch ::= { {+ @ident } } + +with the following requirements: + ++ :token:`tactic` must be one of the four basic tactics described in :ref:`the_defective_tactics_ssr`, + i.e., ``move``, ``case``, ``elim`` or ``apply``, the ``exact`` + tactic (section :ref:`terminators_ssr`), + the ``congr`` tactic (section :ref:`congruence_ssr`), + or the application of the *view* + tactical ‘/’ (section :ref:`interpreting_assumptions_ssr`) to one of move, case, or elim. ++ The optional :token:`ident` specifies *equation generation* (section :ref:`generation_of_equations_ssr`), + and is only allowed if tactic is ``move``, ``case`` or ``elim``, or the + application of the view tactical ‘/’ (section :ref:`interpreting_assumptions_ssr`) to ``case`` or ``elim``. ++ An :token:`occ_switch` selects occurrences of :token:`term`, as in :ref:`abbreviations_ssr`; :token:`occ_switch` + is not allowed if :token:`tactic` is ``apply`` or ``exact``. ++ A clear item :token:`clear_switch` specifies facts and constants to be + deleted from the proof context (as per the clear tactic). + + +The ``:`` tactical first *discharges* all the :token:`d_item`, right to left, +and then performs tactic, i.e., for each :token:`d_item`, starting with the last one : + + +#. The |SSR| matching algorithm described in section :ref:`abbreviations_ssr` is + used to find occurrences of term in the goal, after filling any holes + ‘_’ in term; however if tactic is apply or exact a different matching + algorithm, described below, is used [#4]_. +#. These occurrences are replaced by a new variable; in particular, if + term is a fact, this adds an assumption to the goal. +#. If term is *exactly* the name of a constant or fact in the proof + context, it is deleted from the context, unless there is an + :token:`occ_switch`. + + +Finally, tactic is performed just after the first :token:`d_item` +has been generalized +— that is, between steps 2 and 3. The names listed in +the final :token:`clear_switch` (if it is present) are cleared first, before +:token:`d_item` n is discharged. + +Switches affect the discharging of a :token:`d_item` as follows: + + ++ An :token:`occ_switch` restricts generalization (step 2) to a specific subset + of the occurrences of term, as per section :ref:`abbreviations_ssr`, and prevents clearing (step + 3). ++ All the names specified by a :token:`clear_switch` are deleted from the + context in step 3, possibly in addition to term. + + +For example, the tactic: + +.. coqdoc:: + + move: n {2}n (refl_equal n). + ++ first generalizes ``(refl_equal n : n = n)``; ++ then generalizes the second occurrence of ``n``. ++ finally generalizes all the other occurrences of ``n``, and clears ``n`` + from the proof context (assuming n is a proof constant). + +Therefore this tactic changes any goal ``G`` into + +.. coqdoc:: + + forall n n0 : nat, n = n0 -> G. + +where the name ``n0`` is picked by the |Coq| display function, and assuming +``n`` appeared only in ``G``. + +Finally, note that a discharge operation generalizes defined constants +as variables, and not as local definitions. To override this behavior, +prefix the name of the local definition with a ``@``, like in ``move: @n``. + +This is in contrast with the behavior of the in tactical (see +section :ref:`localization_ssr`), which preserves local +definitions by default. + + +Clear rules +``````````` + +The clear step will fail if term is a proof constant that appears in +other facts; in that case either the facts should be cleared +explicitly with a :token:`clear_switch`, or the clear step should be disabled. +The latter can be done by adding an :token:`occ_switch` or simply by putting +parentheses around term: both +``move: (n).`` +and +``move: {+}n.`` +generalize ``n`` without clearing ``n`` from the proof context. + +The clear step will also fail if the :token:`clear_switch` contains a :token:`ident` that +is not in the *proof* context. Note that |SSR| never clears a +section constant. + +If tactic is ``move`` or ``case`` and an equation :token:`ident` is given, then clear +(step 3) for :token:`d_item` is suppressed (see section :ref:`generation_of_equations_ssr`). + +Intro patterns (see section :ref:`introduction_ssr`) +and the ``rewrite`` tactic (see section :ref:`rewriting_ssr`) +let one place a :token:`clear_switch` in the middle of other items +(namely identifiers, views and rewrite rules). This can trigger the +addition of proof context items to the ones being explicitly +cleared, and in turn this can result in clear errors (e.g. if the +context item automatically added occurs in the goal). The +relevant sections describe ways to avoid the unintended clear of +context items. + + +Matching for apply and exact +```````````````````````````` + +The matching algorithm for :token:`d_item` of the |SSR| +``apply`` and ``exact`` +tactics exploits the type of the first :token:`d_item` to interpret +wildcards in the +other :token:`d_item` and to determine which occurrences of these should be +generalized. Therefore, occur switches are not needed for apply and +exact. + +Indeed, the |SSR| tactic ``apply: H x`` is equivalent to +``refine (@H _ … _ x); clear H x`` +with an appropriate number of wildcards between ``H`` and ``x``. + +Note that this means that matching for ``apply`` and ``exact`` has much more +context to interpret wildcards; in particular it can accommodate the +``_`` :token:`d_item`, which would always be rejected after ``move:``. + +.. example:: + + .. coqtop:: reset none + + From Coq Require Import ssreflect. + Set Implicit Arguments. + Unset Strict Implicit. + Unset Printing Implicit Defensive. + Axiom f : nat -> nat. + Axiom g : nat -> nat. + + .. coqtop:: all + + Lemma test (Hfg : forall x, f x = g x) a b : f a = g b. + apply: trans_equal (Hfg _) _. + +This tactic is equivalent (see section +:ref:`bookkeeping_ssr`) to: +``refine (trans_equal (Hfg _) _).`` +and this is a common idiom for applying transitivity on the left hand +side of an equation. + + +.. _abstract_ssr: + +The abstract tactic +``````````````````` + +.. tacn:: abstract: {+ d_item} + :name: abstract (ssreflect) + + This tactic assigns an abstract constant previously introduced with the + :n:`[: @ident ]` intro pattern (see section :ref:`introduction_ssr`). + +In a goal like the following:: + + m : nat + abs : <hidden> + n : nat + ============= + m < 5 + n + +The tactic ``abstract: abs n`` first generalizes the goal with respect ton +(that is not visible to the abstract constant abs) and then assigns +abs. The resulting goal is:: + + m : nat + n : nat + ============= + m < 5 + n + +Once this subgoal is closed, all other goals having abs in their +context see the type assigned to ``abs``. In this case:: + + m : nat + abs : forall n, m < 5 + n + ============= + … + +For a more detailed example the reader should refer to +section :ref:`structure_ssr`. + + +.. _introduction_ssr: + +Introduction in the context +~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +The application of a tactic to a given goal can generate (quantified) +variables, assumptions, or definitions, which the user may want to +*introduce* as new facts, constants or defined constants, +respectively. If the tactic splits the goal into several subgoals, +each of them may require the introduction of different constants and +facts. Furthermore it is very common to immediately decompose or +rewrite with an assumption instead of adding it to the context, as the +goal can often be simplified and even proved after this. + +All these operations are performed by the introduction tactical ``=>``, +whose general syntax is + +.. tacn:: @tactic => {+ @i_item } + :name: => + :undocumented: + +.. prodn:: + i_item ::= @i_pattern %| @s_item %| @clear_switch %| @i_view %| @i_block + +.. prodn:: + s_item ::= /= %| // %| //= + +.. prodn:: + i_view ::= {? %{%} } /@term %| /ltac:( @tactic ) + +.. prodn:: + i_pattern ::= @ident %| > %| _ %| ? %| * %| + %| {? @occ_switch } -> %| {? @occ_switch }<- %| [ {?| @i_item } ] %| - %| [: {+ @ident } ] + +.. prodn:: + i_block ::= [^ @ident ] %| [^~ @ident ] %| [^~ @num ] + +The ``=>`` tactical first executes :token:`tactic`, then the :token:`i_item`\s, +left to right. An :token:`s_item` specifies a +simplification operation; a :token:`clear_switch` +specifies context pruning as in :ref:`discharge_ssr`. +The :token:`i_pattern`\s can be seen as a variant of *intro patterns* +(see :tacn:`intros`:) each performs an introduction operation, i.e., pops some +variables or assumptions from the goal. + +Simplification items +````````````````````` + +An :token:`s_item` can simplify the set of subgoals or the subgoals themselves: + ++ ``//`` removes all the “trivial” subgoals that can be resolved by the + |SSR| tactic :tacn:`done` described in :ref:`terminators_ssr`, i.e., + it executes ``try done``. ++ ``/=`` simplifies the goal by performing partial evaluation, as per the + tactic :tacn:`simpl` [#5]_. ++ ``//=`` combines both kinds of simplification; it is equivalent to + ``/= //``, i.e., ``simpl; try done``. + + +When an :token:`s_item` immediately precedes a :token:`clear_switch`, then the +:token:`clear_switch` is executed +*after* the :token:`s_item`, e.g., ``{IHn}//`` will solve some subgoals, +possibly using the fact ``IHn``, and will erase ``IHn`` from the context +of the remaining subgoals. + +Views +````` + +The first entry in the :token:`i_view` grammar rule, :n:`/@term`, +represents a view (see section :ref:`views_and_reflection_ssr`). +It interprets the top of the stack with the view :token:`term`. +It is equivalent to :n:`move/@term`. + +A :token:`clear_switch` that immediately precedes an :token:`i_view` +is complemented with the name of the view if an only if the :token:`i_view` +is a simple proof context entry [#10]_. +E.g. ``{}/v`` is equivalent to ``/v{v}``. +This behavior can be avoided by separating the :token:`clear_switch` +from the :token:`i_view` with the ``-`` intro pattern or by putting +parentheses around the view. + +A :token:`clear_switch` that immediately precedes an :token:`i_view` +is executed after the view application. + + +If the next :token:`i_item` is a view, then the view is +applied to the assumption in top position once all the +previous :token:`i_item` have been performed. + +The second entry in the :token:`i_view` grammar rule, +``/ltac:(`` :token:`tactic` ``)``, executes :token:`tactic`. +Notations can be used to name tactics, for example:: + + Notation myop := (ltac:(some ltac code)) : ssripat_scope. + +lets one write just ``/myop`` in the intro pattern. Note the scope +annotation: views are interpreted opening the ``ssripat`` scope. + +Intro patterns +`````````````` + +|SSR| supports the following :token:`i_pattern`\s: + +:token:`ident` + pops the top variable, assumption, or local definition into + a new constant, fact, or defined constant :token:`ident`, respectively. + Note that defined constants cannot be introduced when δ-expansion is + required to expose the top variable or assumption. + A :token:`clear_switch` (even an empty one) immediately preceding an + :token:`ident` is complemented with that :token:`ident` if and only if + the identifier is a simple proof context entry [#10]_. + As a consequence by prefixing the + :token:`ident` with ``{}`` one can *replace* a context entry. + This behavior can be avoided by separating the :token:`clear_switch` + from the :token:`ident` with the ``-`` intro pattern. +``>`` + pops every variable occurring in the rest of the stack. + Type class instances are popped even if they don't occur + in the rest of the stack. + The tactic ``move=> >`` is equivalent to + ``move=> ? ?`` on a goal such as:: + + forall x y, x < y -> G + + A typical use if ``move=>> H`` to name ``H`` the first assumption, + in the example above ``x < y``. +``?`` + pops the top variable into an anonymous constant or fact, whose name + is picked by the tactic interpreter. |SSR| only generates names that cannot + appear later in the user script [#6]_. +``_`` + pops the top variable into an anonymous constant that will be deleted + from the proof context of all the subgoals produced by the ``=>`` tactical. + They should thus never be displayed, except in an error message if the + constant is still actually used in the goal or context after the last + :token:`i_item` has been executed (:token:`s_item` can erase goals or + terms where the constant appears). +``*`` + pops all the remaining apparent variables/assumptions as anonymous + constants/facts. Unlike ``?`` and ``move`` the ``*`` + :token:`i_item` does not + expand definitions in the goal to expose quantifiers, so it may be useful + to repeat a ``move=> *`` tactic, e.g., on the goal:: + + forall a b : bool, a <> b + + a first ``move=> *`` adds only ``_a_ : bool`` and ``_b_ : bool`` + to the context; it takes a second ``move=> *`` to add ``_Hyp_ : _a_ = _b_``. +``+`` + temporarily introduces the top variable. It is discharged at the end + of the intro pattern. For example ``move=> + y`` on a goal:: + + forall x y, P + + is equivalent to ``move=> _x_ y; move: _x_`` that results in the goal:: + + forall x, P + +:n:`{? occ_switch } ->` + (resp. :token:`occ_switch` ``<-``) + pops the top assumption (which should be a rewritable proposition) into an + anonymous fact, rewrites (resp. rewrites right to left) the goal with this + fact (using the |SSR| ``rewrite`` tactic described in section + :ref:`rewriting_ssr`, and honoring the optional occurrence selector), and + finally deletes the anonymous fact from the context. +``[`` :token:`i_item` * ``| … |`` :token:`i_item` * ``]`` + when it is the + very *first* :token:`i_pattern` after tactic ``=>`` tactical *and* tactic + is not a move, is a *branching*:token:`i_pattern`. It executes the sequence + :token:`i_item`:math:`_i` on the i-th subgoal produced by tactic. The + execution of tactic should thus generate exactly m subgoals, unless the + ``[…]`` :token:`i_pattern` comes after an initial ``//`` or ``//=`` + :token:`s_item` that closes some of the goals produced by ``tactic``, in + which case exactly m subgoals should remain after thes- item, or we have + the trivial branching :token:`i_pattern` [], which always does nothing, + regardless of the number of remaining subgoals. +``[`` :token:`i_item` * ``| … |`` :token:`i_item` * ``]`` + when it is *not* + the first :token:`i_pattern` or when tactic is a ``move``, is a + *destructing* :token:`i_pattern`. It starts by destructing the top + variable, using the |SSR| ``case`` tactic described in + :ref:`the_defective_tactics_ssr`. It then behaves as the corresponding + branching :token:`i_pattern`, executing the + sequence :n:`@i_item__i` in the i-th subgoal generated by the + case analysis; unless we have the trivial destructing :token:`i_pattern` + ``[]``, the latter should generate exactly m subgoals, i.e., the top + variable should have an inductive type with exactly m constructors [#7]_. + While it is good style to use the :token:`i_item` i * to pop the variables + and assumptions corresponding to each constructor, this is not enforced by + |SSR|. +``-`` + does nothing, but counts as an intro pattern. It can also be used to + force the interpretation of ``[`` :token:`i_item` * ``| … |`` + :token:`i_item` * ``]`` as a case analysis like in ``move=> -[H1 H2]``. It + can also be used to indicate explicitly the link between a view and a name + like in ``move=> /eqP-H1``. Last, it can serve as a separator between + views. Section :ref:`views_and_reflection_ssr` [#9]_ explains in which + respect the tactic ``move=> /v1/v2`` differs from the tactic ``move=> + /v1-/v2``. +``[:`` :token:`ident` ``…]`` + introduces in the context an abstract constant + for each :token:`ident`. Its type has to be fixed later on by using the + ``abstract`` tactic. Before then the type displayed is ``<hidden>``. + + +Note that |SSR| does not support the syntax ``(ipat, …, ipat)`` for +destructing intro-patterns. + +Clear switch +```````````` + +Clears are deferred until the end of the intro pattern. + +.. example:: + + .. coqtop:: reset none + + From Coq Require Import ssreflect ssrbool. + Set Implicit Arguments. + Unset Strict Implicit. + Unset Printing Implicit Defensive. + + .. coqtop:: all + + Lemma test x y : Nat.leb 0 x = true -> (Nat.leb 0 x) && (Nat.leb y 2) = true. + move=> {x} ->. + +If the cleared names are reused in the same intro pattern, a renaming +is performed behind the scenes. + +Facts mentioned in a clear switch must be valid names in the proof +context (excluding the section context). + +Branching and destructuring +``````````````````````````` + +The rules for interpreting branching and destructing :token:`i_pattern` are +motivated by the fact that it would be pointless to have a branching +pattern if tactic is a ``move``, and in most of the remaining cases +tactic is ``case`` or ``elim``, which implies destruction. +The rules above imply that: + ++ ``move=> [a b].`` ++ ``case=> [a b].`` ++ ``case=> a b.`` + +are all equivalent, so which one to use is a matter of style; ``move`` should +be used for casual decomposition, such as splitting a pair, and ``case`` +should be used for actual decompositions, in particular for type families +(see :ref:`type_families_ssr`) and proof by contradiction. + +The trivial branching :token:`i_pattern` can be used to force the branching +interpretation, e.g.: + ++ ``case=> [] [a b] c.`` ++ ``move=> [[a b] c].`` ++ ``case; case=> a b c.`` + +are all equivalent. + +Block introduction +`````````````````` + +|SSR| supports the following :token:`i_block`\s: + +:n:`[^ @ident ]` + *block destructing* :token:`i_pattern`. It performs a case analysis + on the top variable and introduces, in one go, all the variables coming + from the case analysis. The names of these variables are obtained by + taking the names used in the inductive type declaration and prefixing them + with :token:`ident`. If the intro pattern immediately follows a call + to ``elim`` with a custom eliminator (see :ref:`custom_elim_ssr`) then + the names are taken from the ones used in the type of the eliminator. + + .. example:: + + .. coqtop:: reset none + + From Coq Require Import ssreflect. + Set Implicit Arguments. + Unset Strict Implicit. + Unset Printing Implicit Defensive. + + .. coqtop:: all + + Record r := { a : nat; b := (a, 3); _ : bool; }. + + Lemma test : r -> True. + Proof. move => [^ x ]. + +:n:`[^~ @ident ]` + *block destructing* using :token:`ident` as a suffix. +:n:`[^~ @num ]` + *block destructing* using :token:`num` as a suffix. + + Only a :token:`s_item` is allowed between the elimination tactic and + the block destructing. + +.. _generation_of_equations_ssr: + +Generation of equations +~~~~~~~~~~~~~~~~~~~~~~~ + +The generation of named equations option stores the definition of a +new constant as an equation. The tactic: + +.. coqdoc:: + + move En: (size l) => n. + +where ``l`` is a list, replaces ``size l`` by ``n`` in the goal and +adds the fact ``En : size l = n`` to the context. +This is quite different from: + +.. coqdoc:: + + pose n := (size l). + +which generates a definition ``n := (size l)``. It is not possible to +generalize or rewrite such a definition; on the other hand, it is +automatically expanded during computation, whereas expanding the +equation ``En`` requires explicit rewriting. + +The use of this equation name generation option with a ``case`` or an +``elim`` tactic changes the status of the first :token:`i_item`, in order to +deal with the possible parameters of the constants introduced. + +.. example:: + + .. coqtop:: reset none + + From Coq Require Import ssreflect. + Set Implicit Arguments. + Unset Strict Implicit. + Unset Printing Implicit Defensive. + + .. coqtop:: all + + Lemma test (a b :nat) : a <> b. + case E : a => [|n]. + +If the user does not provide a branching :token:`i_item` as first +:token:`i_item`, or if the :token:`i_item` does not provide enough names for +the arguments of a constructor, then the constants generated are introduced +under fresh |SSR| names. + +.. example:: + + .. coqtop:: reset none + + From Coq Require Import ssreflect. + Set Implicit Arguments. + Unset Strict Implicit. + Unset Printing Implicit Defensive. + + .. coqtop:: all + + Lemma test (a b :nat) : a <> b. + case E : a => H. + Show 2. + +Combining the generation of named equations mechanism with thecase +tactic strengthens the power of a case analysis. On the other hand, +when combined with the elim tactic, this feature is mostly useful for +debug purposes, to trace the values of decomposed parameters and +pinpoint failing branches. + + +.. _type_families_ssr: + +Type families +~~~~~~~~~~~~~ + +When the top assumption of a goal has an inductive type, two specific +operations are possible: the case analysis performed by the :tacn:`case` +tactic, and the application of an induction principle, performed by +the :tacn:`elim` tactic. When this top assumption has an inductive type, which +is moreover an instance of a type family, |Coq| may need help from the +user to specify which occurrences of the parameters of the type should +be substituted. + +.. tacv:: case: {+ @d_item } / {+ @d_item } + elim: {+ @d_item } / {+ @d_item } + + A specific ``/`` switch indicates the type family parameters of the type + of a :token:`d_item` immediately following this ``/`` switch. + The :token:`d_item` on the right side of the ``/`` switch are discharged as + described in section :ref:`discharge_ssr`. The case analysis or elimination + will be done on the type of the top assumption after these discharge + operations. + + Every :token:`d_item` preceding the ``/`` is interpreted as arguments of this + type, which should be an instance of an inductive type family. These terms + are not actually generalized, but rather selected for substitution. + Occurrence switches can be used to restrict the substitution. If a term is + left completely implicit (e.g. writing just ``_``), then a pattern is + inferred looking at the type of the top assumption. This allows for the + compact syntax: + + .. coqdoc:: + + case: {2}_ / eqP. + + where ``_`` is interpreted as ``(_ == _)`` since + ``eqP T a b : reflect (a = b) (a == b)`` and reflect is a type family with + one index. + + Moreover if the :token:`d_item` list is too short, it is padded with an + initial sequence of ``_`` of the right length. + + .. example:: + + Here is a small example on lists. We define first a function which + adds an element at the end of a given list. + + .. coqtop:: reset none + + From Coq Require Import ssreflect. + Set Implicit Arguments. + Unset Strict Implicit. + Unset Printing Implicit Defensive. + + .. coqtop:: all + + Require Import List. + Section LastCases. + Variable A : Type. + Implicit Type l : list A. + Fixpoint add_last a l : list A := + match l with + | nil => a :: nil + | hd :: tl => hd :: (add_last a tl) end. + + Then we define an inductive predicate for case analysis on lists + according to their last element: + + .. coqtop:: all + + Inductive last_spec : list A -> Type := + | LastSeq0 : last_spec nil + | LastAdd s x : last_spec (add_last x s). + + Theorem lastP : forall l : list A, last_spec l. + Admitted. + + We are now ready to use ``lastP`` in conjunction with ``case``. + + .. coqtop:: all + + Lemma test l : (length l) * 2 = length (l ++ l). + case: (lastP l). + + Applied to the same goal, the tactc ``case: l / (lastP l)`` + generates the same subgoals but ``l`` has been cleared from both contexts: + + .. coqtop:: all restart + + case: l / (lastP l). + + Again applied to the same goal: + + .. coqtop:: all restart abort + + case: {1 3}l / (lastP l). + + Note that selected occurrences on the left of the ``/`` + switch have been substituted with l instead of being affected by + the case analysis. + + The equation name generation feature combined with a type family ``/`` + switch generates an equation for the *first* dependent :token:`d_item` + specified by the user. Again starting with the above goal, the + command: + + .. example:: + + .. coqtop:: all + + Lemma test l : (length l) * 2 = length (l ++ l). + case E: {1 3}l / (lastP l) => [|s x]. + Show 2. + + + There must be at least one :token:`d_item` to the left of the ``/`` switch; this + prevents any confusion with the view feature. However, the :token:`d_item` + to the right of the ``/`` are optional, and if they are omitted the first + assumption provides the instance of the type family. + + The equation always refers to the first :token:`d_item` in the actual tactic + call, before any padding with initial ``_``. Thus, if an inductive type + has two family parameters, it is possible to have|SSR| generate an + equation for the second one by omitting the pattern for the first; + note however that this will fail if the type of the second parameter + depends on the value of the first parameter. + + +Control flow +------------ + + +.. _indentation_ssr: + +Indentation and bullets +~~~~~~~~~~~~~~~~~~~~~~~ + +A linear development of |Coq| scripts gives little information on the +structure of the proof. In addition, replaying a proof after some +changes in the statement to be proved will usually not display +information to distinguish between the various branches of case +analysis for instance. + +To help the user in this organization of the proof script at development +time, |SSR| provides some bullets to highlight the structure of branching +proofs. The available bullets are ``-``, ``+`` and ``*``. Combined with +tabulation, this lets us highlight four nested levels of branching; the most +we have ever needed is three. Indeed, the use of “simpl and closing” +switches, of terminators (see above section :ref:`terminators_ssr`) and +selectors (see section :ref:`selectors_ssr`) is powerful enough to avoid most +of the time more than two levels of indentation. + +Here is a fragment of such a structured script:: + + case E1: (abezoutn _ _) => [[| k1] [| k2]]. + - rewrite !muln0 !gexpn0 mulg1 => H1. + move/eqP: (sym_equal F0); rewrite -H1 orderg1 eqn_mul1. + by case/andP; move/eqP. + - rewrite muln0 gexpn0 mulg1 => H1. + have F1: t %| t * S k2.+1 - 1. + apply: (@dvdn_trans (orderg x)); first by rewrite F0; exact: dvdn_mull. + rewrite orderg_dvd; apply/eqP; apply: (mulgI x). + rewrite -{1}(gexpn1 x) mulg1 gexpn_add leq_add_sub //. + by move: P1; case t. + rewrite dvdn_subr in F1; last by exact: dvdn_mulr. + + rewrite H1 F0 -{2}(muln1 (p ^ l)); congr (_ * _). + by apply/eqP; rewrite -dvdn1. + + by move: P1; case: (t) => [| [| s1]]. + - rewrite muln0 gexpn0 mul1g => H1. + ... + + +.. _terminators_ssr: + +Terminators +~~~~~~~~~~~ + +To further structure scripts, |SSR| supplies *terminating* +tacticals to explicitly close off tactics. When replaying scripts, we +then have the nice property that an error immediately occurs when a +closed tactic fails to prove its subgoal. + +It is hence recommended practice that the proof of any subgoal should +end with a tactic which *fails if it does not solve the current goal*, +like :tacn:`discriminate`, :tacn:`contradiction` or :tacn:`assumption`. + +In fact, |SSR| provides a generic tactical which turns any tactic +into a closing one (similar to :tacn:`now`). Its general syntax is: + +.. tacn:: by @tactic + :name: by + :undocumented: + +The Ltac expression :n:`by [@tactic | @tactic | …]` is equivalent to +:n:`do [done | by @tactic | by @tactic | …]`, which corresponds to the +standard Ltac expression :n:`first [done | @tactic; done | @tactic; done | …]`. + +In the script provided as example in section :ref:`indentation_ssr`, the +paragraph corresponding to each sub-case ends with a tactic line prefixed +with a ``by``, like in: + +.. coqdoc:: + + by apply/eqP; rewrite -dvdn1. + +.. tacn:: done + :name: done + + The :tacn:`by` tactical is implemented using the user-defined, and extensible + :tacn:`done` tactic. This :tacn:`done` tactic tries to solve the current goal by some + trivial means and fails if it doesn’t succeed. Indeed, the tactic + expression :n:`by @tactic` is equivalent to :n:`@tactic; done`. + + Conversely, the tactic ``by [ ]`` is equivalent to :tacn:`done`. + + The default implementation of the done tactic, in the ``ssreflect.v`` + file, is: + + .. coqdoc:: + + Ltac done := + trivial; hnf; intros; solve + [ do ![solve [trivial | apply: sym_equal; trivial] + | discriminate | contradiction | split] + | case not_locked_false_eq_true; assumption + | match goal with H : ~ _ |- _ => solve [case H; trivial] end ]. + + The lemma :g:`not_locked_false_eq_true` is needed to discriminate + *locked* boolean predicates (see section :ref:`locking_ssr`). The iterator + tactical do is presented in section :ref:`iteration_ssr`. This tactic can be + customized by the user, for instance to include an :tacn:`auto` tactic. + +A natural and common way of closing a goal is to apply a lemma which +is the exact one needed for the goal to be solved. The defective form +of the tactic: + +.. coqdoc:: + + exact. + +is equivalent to: + +.. coqdoc:: + + do [done | by move=> top; apply top]. + +where ``top`` is a fresh name assigned to the top assumption of the goal. +This applied form is supported by the ``:`` discharge tactical, and the +tactic: + +.. coqdoc:: + + exact: MyLemma. + +is equivalent to: + +.. coqdoc:: + + by apply: MyLemma. + +(see section :ref:`discharge_ssr` for the documentation of the apply: combination). + +.. warning:: + + The list of tactics (possibly chained by semicolons) that + follows the ``by`` keyword is considered to be a parenthesized block applied to + the current goal. Hence for example if the tactic: + + .. coqdoc:: + + by rewrite my_lemma1. + + succeeds, then the tactic: + + .. coqdoc:: + + by rewrite my_lemma1; apply my_lemma2. + + usually fails since it is equivalent to: + + .. coqdoc:: + + by (rewrite my_lemma1; apply my_lemma2). + + +.. _selectors_ssr: + +Selectors +~~~~~~~~~ + +.. tacn:: last + first + :name: last; first (ssreflect) + + When composing tactics, the two tacticals ``first`` and ``last`` let the user + restrict the application of a tactic to only one of the subgoals + generated by the previous tactic. This covers the frequent cases where + a tactic generates two subgoals one of which can be easily disposed + of. + + This is another powerful way of linearization of scripts, since it + happens very often that a trivial subgoal can be solved in a less than + one line tactic. For instance, :n:`@tactic ; last by @tactic` + tries to solve the last subgoal generated by the first + tactic using the given second tactic, and fails if it does not succeed. + Its analogue :n:`@tactic ; first by @tactic` + tries to solve the first subgoal generated by the first tactic using the + second given tactic, and fails if it does not succeed. + +|SSR| also offers an extension of this facility, by supplying +tactics to *permute* the subgoals generated by a tactic. + +.. tacv:: last first + first last + :name: last first; first last + + These two equivalent tactics invert the order of the subgoals in focus. + + .. tacv:: last @num first + + If :token:`num`\'s value is :math:`k`, + this tactic rotates the :math:`n` subgoals :math:`G_1` , …, :math:`G_n` + in focus. The first subgoal becomes :math:`G_{n + 1 − k}` and the + circular order of subgoals remains unchanged. + + .. tacn:: first @num last + + If :token:`num`\'s value is :math:`k`, + this tactic rotates the :math:`n` subgoals :math:`G_1` , …, :math:`G_n` + in focus. The first subgoal becomes :math:`G_k` and the circular order + of subgoals remains unchanged. + +Finally, the tactics ``last`` and ``first`` combine with the branching syntax +of Ltac: if the tactic generates n subgoals on a given goal, +then the tactic + +.. coqdoc:: + + tactic ; last k [ tactic1 |…| tacticm ] || tacticn. + +where natural denotes the integer k as above, applies tactic1 to the n +−k + 1-th goal, … tacticm to the n −k + 2 − m-th goal and tactic n +to the others. + +.. example:: + + Here is a small example on lists. We define first a function which + adds an element at the end of a given list. + + .. coqtop:: reset none + + From Coq Require Import ssreflect. + Set Implicit Arguments. + Unset Strict Implicit. + Unset Printing Implicit Defensive. + + .. coqtop:: all + + Inductive test : nat -> Prop := + | C1 n of n = 1 : test n + | C2 n of n = 2 : test n + | C3 n of n = 3 : test n + | C4 n of n = 4 : test n. + + Lemma example n (t : test n) : True. + case: t; last 2 [move=> k| move=> l]; idtac. + + +.. _iteration_ssr: + +Iteration +~~~~~~~~~ + +.. tacn:: do {? @num } ( @tactic | [ {+| @tactic } ] ) + :name: do (ssreflect) + + This tactical offers an accurate control on the repetition of tactics. + :token:`mult` is a *multiplier*. + + Brackets can only be omitted if a single tactic is given *and* a + multiplier is present. + +A tactic of the form: + +.. coqdoc:: + + do [ tactic 1 | … | tactic n ]. + +is equivalent to the standard Ltac expression: + +.. coqdoc:: + + first [ tactic 1 | … | tactic n ]. + +The optional multiplier :token:`mult` specifies how many times the action of +tactic should be repeated on the current subgoal. + +There are four kinds of multipliers: + +.. prodn:: + mult ::= @num ! %| ! %| @num ? %| ? + +Their meaning is: + ++ ``n!`` the step tactic is repeated exactly n times (where n is a + positive integer argument). ++ ``!`` the step tactic is repeated as many times as possible, and done + at least once. ++ ``?`` the step tactic is repeated as many times as possible, + optionally. ++ ``n?`` the step tactic is repeated up to n times, optionally. + + +For instance, the tactic: + +.. coqdoc:: + + tactic; do 1? rewrite mult_comm. + +rewrites at most one time the lemma ``mult_comm`` in all the subgoals +generated by tactic , whereas the tactic: + +.. coqdoc:: + + tactic; do 2! rewrite mult_comm. + +rewrites exactly two times the lemma ``mult_comm`` in all the subgoals +generated by tactic, and fails if this rewrite is not possible in some +subgoal. + +Note that the combination of multipliers and rewrite is so often used +that multipliers are in fact integrated to the syntax of the +|SSR| rewrite tactic, see section :ref:`rewriting_ssr`. + + +.. _localization_ssr: + +Localization +~~~~~~~~~~~~ + +In sections :ref:`basic_localization_ssr` and :ref:`bookkeeping_ssr`, we have +already presented the *localization* tactical in, whose general syntax is: + +.. tacn:: @tactic in {+ @ident} {? * } + :name: in + :undocumented: + +where :token:`ident` is a name in the +context. On the left side of ``in``, +:token:`tactic` can be ``move``, ``case``, ``elim``, ``rewrite``, ``set``, +or any tactic formed with the general iteration tactical ``do`` (see section +:ref:`iteration_ssr`). + +The operation described by tactic is performed in the facts listed after +``in`` and in the goal if a ``*`` ends the list of names. + +The ``in`` tactical successively: + ++ generalizes the selected hypotheses, possibly “protecting” the goal + if ``*`` is not present, ++ performs :token:`tactic`, on the obtained goal, ++ reintroduces the generalized facts, under the same names. + +This defective form of the ``do`` tactical is useful to avoid clashes +between standard Ltac in and the |SSR| tactical in. + +.. example:: + + .. coqtop:: reset none + + From Coq Require Import ssreflect. + Set Implicit Arguments. + Unset Strict Implicit. + Unset Printing Implicit Defensive. + + .. coqtop:: all + + Ltac mytac H := rewrite H. + + Lemma test x y (H1 : x = y) (H2 : y = 3) : x + y = 6. + do [mytac H2] in H1 *. + + the last tactic rewrites the hypothesis ``H2 : y = 3`` both in + ``H1 : x = y`` and in the goal ``x + y = 6``. + +By default ``in`` keeps the body of local definitions. To erase the body +of a local definition during the generalization phase, the name of the +local definition must be written between parentheses, like in +``rewrite H in H1 (def_n) H2.`` + +.. tacv:: @tactic in {+ @clear_switch | {? @ } @ident | ( @ident ) | ( {? @ } @ident := @c_pattern ) } {? * } + + This is the most general form of the ``in`` tactical. + In its simplest form the last option lets one rename hypotheses that + can’t be cleared (like section variables). For example, ``(y := x)`` + generalizes over ``x`` and reintroduces the generalized variable under the + name ``y`` (and does not clear ``x``). + For a more precise description of this form of localization refer + to :ref:`advanced_generalization_ssr`. + + +.. _structure_ssr: + +Structure +~~~~~~~~~ + +Forward reasoning structures the script by explicitly specifying some +assumptions to be added to the proof context. It is closely associated +with the declarative style of proof, since an extensive use of these +highlighted statements make the script closer to a (very detailed) +textbook proof. + +Forward chaining tactics allow to state an intermediate lemma and start a +piece of script dedicated to the proof of this statement. The use of closing +tactics (see section :ref:`terminators_ssr`) and of indentation makes +syntactically explicit the portion of the script building the proof of the +intermediate statement. + + +The have tactic. +```````````````` + +.. tacn:: have : @term + :name: have + + This is the main |SSR| forward reasoning tactic. It can + be used in two modes: one starts a new (sub)proof for an intermediate + result in the main proof, and the other provides explicitly a proof + term for this intermediate step. + + This tactic supports open syntax for :token:`term`. Applied to a goal ``G``, it + generates a first subgoal requiring a proof of :token:`term` in the context of + ``G``. The second generated subgoal is of the form :n:`term -> G`, where term + becomes the new top assumption, instead of being introduced with a + fresh name. At the proof-term level, the have tactic creates a β + redex, and introduces the lemma under a fresh name, automatically + chosen. + +Like in the case of the :n:`pose (ssreflect)` tactic (see section :ref:`definitions_ssr`), the types of +the holes are abstracted in term. + +.. example:: + + .. coqtop:: reset none + + From Coq Require Import ssreflect. + Set Implicit Arguments. + Unset Strict Implicit. + Unset Printing Implicit Defensive. + + .. coqtop:: all + + Lemma test : True. + have: _ * 0 = 0. + + The invokation of ``have`` is equivalent to: + + .. coqtop:: reset none + + From Coq Require Import ssreflect. + Set Implicit Arguments. + Unset Strict Implicit. + Unset Printing Implicit Defensive. + Lemma test : True. + + .. coqtop:: all + + have: forall n : nat, n * 0 = 0. + +The have tactic also enjoys the same abstraction mechanism as the ``pose`` +tactic for the non-inferred implicit arguments. For instance, the +tactic: + +.. example:: + + .. coqtop:: reset none + + From Coq Require Import ssreflect. + Set Implicit Arguments. + Unset Strict Implicit. + Unset Printing Implicit Defensive. + Lemma test : True. + + .. coqtop:: all + + have: forall x y, (x, y) = (x, y + 0). + + opens a new subgoal where the type of ``x`` is quantified. + +The behavior of the defective have tactic makes it possible to +generalize it in the following general construction: + +.. tacn:: have {* @i_item } {? @i_pattern } {? @s_item | {+ @ssr_binder } } {? : @term } {? := @term | by @tactic } + :undocumented: + +Open syntax is supported for both :token:`term`. For the description +of :token:`i_item` and :token:`s_item` see section +:ref:`introduction_ssr`. The first mode of the +have tactic, which opens a sub-proof for an intermediate result, uses +tactics of the form: + +.. tacv:: have @clear_switch @i_item : @term by @tactic + :undocumented: + +which behave like: + +.. coqdoc:: + + have: term ; first by tactic. + move=> clear_switch i_item. + +Note that the :token:`clear_switch` *precedes* the:token:`i_item`, which +allows to reuse +a name of the context, possibly used by the proof of the assumption, +to introduce the new assumption itself. + +The ``by`` feature is especially convenient when the proof script of the +statement is very short, basically when it fits in one line like in: + +.. coqdoc:: + + have H23 : 3 + 2 = 2 + 3 by rewrite addnC. + +The possibility of using :token:`i_item` supplies a very concise syntax for +the further use of the intermediate step. For instance, + +.. example:: + + .. coqtop:: reset none + + From Coq Require Import ssreflect. + Set Implicit Arguments. + Unset Strict Implicit. + Unset Printing Implicit Defensive. + + .. coqtop:: all + + Lemma test a : 3 * a - 1 = a. + have -> : forall x, x * a = a. + + Note how the second goal was rewritten using the stated equality. + Also note that in this last subgoal, the intermediate result does not + appear in the context. + +Thanks to the deferred execution of clears, the following idiom is +also supported (assuming x occurs in the goal only): + +.. coqdoc:: + + have {x} -> : x = y. + +Another frequent use of the intro patterns combined with ``have`` is the +destruction of existential assumptions like in the tactic: + +.. example:: + + .. coqtop:: reset none + + From Coq Require Import ssreflect. + Set Implicit Arguments. + Unset Strict Implicit. + Unset Printing Implicit Defensive. + + .. coqtop:: all + + Lemma test : True. + have [x Px]: exists x : nat, x > 0; last first. + +An alternative use of the ``have`` tactic is to provide the explicit proof +term for the intermediate lemma, using tactics of the form: + +.. tacv:: have {? @ident } := term + + This tactic creates a new assumption of type the type of :token:`term`. + If the + optional :token:`ident` is present, this assumption is introduced under the + name :token:`ident`. Note that the body of the constant is lost for the user. + + Again, non inferred implicit arguments and explicit holes are + abstracted. + +.. example:: + + .. coqtop:: reset none + + From Coq Require Import ssreflect. + Set Implicit Arguments. + Unset Strict Implicit. + Unset Printing Implicit Defensive. + + .. coqtop:: all + + Lemma test : True. + have H := forall x, (x, x) = (x, x). + + adds to the context ``H : Type -> Prop.`` This is a schematic example but + the feature is specially useful when the proof term to give involves + for instance a lemma with some hidden implicit arguments. + +After the :token:`i_pattern`, a list of binders is allowed. + + +.. example:: + + .. coqtop:: reset none + + From Coq Require Import ssreflect. + From Coq Require Import Omega. + Set Implicit Arguments. + Unset Strict Implicit. + Unset Printing Implicit Defensive. + + .. coqtop:: all + + Lemma test : True. + have H x (y : nat) : 2 * x + y = x + x + y by omega. + +A proof term provided after ``:=`` can mention these bound variables +(that are automatically introduced with the given names). +Since the :token:`i_pattern` can be omitted, to avoid ambiguity, +bound variables can be surrounded +with parentheses even if no type is specified: + +.. coqtop:: all restart + + have (x) : 2 * x = x + x by omega. + +The :token:`i_item` and :token:`s_item` can be used to interpret the asserted +hypothesis with views (see section :ref:`views_and_reflection_ssr`) or simplify the resulting +goals. + +The ``have`` tactic also supports a ``suff`` modifier which allows for +asserting that a given statement implies the current goal without +copying the goal itself. + +.. example:: + + .. coqtop:: all restart abort + + have suff H : 2 + 2 = 3; last first. + + Note that H is introduced in the second goal. + +The ``suff`` modifier is not +compatible with the presence of a list of binders. + +.. _generating_let_ssr: + +Generating let in context entries with have +``````````````````````````````````````````` + +Since |SSR| 1.5 the ``have`` tactic supports a “transparent” modifier +to generate let in context entries: the ``@`` symbol in front of the +context entry name. + +.. example:: + + .. coqtop:: none + + Set Printing Depth 15. + + .. coqtop:: all abort + + Inductive Ord n := Sub x of x < n. + Notation "'I_ n" := (Ord n) (at level 8, n at level 2, format "''I_' n"). + Arguments Sub {_} _ _. + + Lemma test n m (H : m + 1 < n) : True. + have @i : 'I_n by apply: (Sub m); omega. + +Note that the sub-term produced by ``omega`` is in general huge and +uninteresting, and hence one may want to hide it. +For this purpose the ``[: name ]`` intro pattern and the tactic +``abstract`` (see :ref:`abstract_ssr`) are provided. + +.. example:: + + .. coqtop:: all abort + + Lemma test n m (H : m + 1 < n) : True. + have [:pm] @i : 'I_n by apply: (Sub m); abstract: pm; omega. + + The type of ``pm`` can be cleaned up by its annotation ``(*1*)`` by just + simplifying it. The annotations are there for technical reasons only. + +When intro patterns for abstract constants are used in conjunction +with have and an explicit term, they must be used as follows: + +.. example:: + + .. coqtop:: all abort + + Lemma test n m (H : m + 1 < n) : True. + have [:pm] @i : 'I_n := Sub m pm. + by omega. + +In this case the abstract constant ``pm`` is assigned by using it in +the term that follows ``:=`` and its corresponding goal is left to be +solved. Goals corresponding to intro patterns for abstract constants +are opened in the order in which the abstract constants are declared +(not in the “order” in which they are used in the term). + +Note that abstract constants do respect scopes. Hence, if a variable +is declared after their introduction, it has to be properly +generalized (i.e. explicitly passed to the abstract constant when one +makes use of it). + +.. example:: + + .. coqtop:: all abort + + Lemma test n m (H : m + 1 < n) : True. + have [:pm] @i k : 'I_(n+k) by apply: (Sub m); abstract: pm k; omega. + +Last, notice that the use of intro patterns for abstract constants is +orthogonal to the transparent flag ``@`` for have. + + +The have tactic and typeclass resolution +``````````````````````````````````````````` + +Since |SSR| 1.5 the ``have`` tactic behaves as follows with respect to +typeclass inference. + + .. coqtop:: none + + Axiom ty : Type. + Axiom t : ty. + + Goal True. + + .. coqtop:: all + + have foo : ty. + + Full inference for ``ty``. The first subgoal demands a + proof of such instantiated statement. + + .. A strange bug prevents using the coqtop directive here + + .. coqdoc:: + + have foo : ty := . + + No inference for ``ty``. Unresolved instances are + quantified in ``ty``. The first subgoal demands a proof of such quantified + statement. Note that no proof term follows ``:=``, hence two subgoals are + generated. + + .. coqtop:: all restart + + have foo : ty := t. + + No inference for ``ty`` and ``t``. + + .. coqtop:: all restart abort + + have foo := t. + + No inference for ``t``. Unresolved instances are + quantified in the (inferred) type of ``t`` and abstracted in ``t``. + +.. flag:: SsrHave NoTCResolution + + This option restores the behavior of |SSR| 1.4 and below (never resolve typeclasses). + +Variants: the suff and wlog tactics +``````````````````````````````````` + +As it is often the case in mathematical textbooks, forward reasoning +may be used in slightly different variants. One of these variants is +to show that the intermediate step L easily implies the initial goal +G. By easily we mean here that the proof of L ⇒ G is shorter than the +one of L itself. This kind of reasoning step usually starts with: “It +suffices to show that …”. + +This is such a frequent way of reasoning that |SSR| has a variant +of the ``have`` tactic called ``suffices`` (whose abridged name is ``suff``). +The +``have`` and ``suff`` tactics are equivalent and have the same syntax but: + + ++ the order of the generated subgoals is inversed ++ but the optional clear item is still performed in the *second* + branch. This means that the tactic: + + .. coqdoc:: + + suff {H} H : forall x : nat, x >= 0. + + fails if the context of the current goal indeed contains an + assumption named ``H``. + + +The rationale of this clearing policy is to make possible “trivial” +refinements of an assumption, without changing its name in the main +branch of the reasoning. + +The ``have`` modifier can follow the ``suff`` tactic. + +.. example:: + + .. coqtop:: none + + Axioms G P : Prop. + + .. coqtop:: all abort + + Lemma test : G. + suff have H : P. + + Note that, in contrast with ``have suff``, the name H has been introduced + in the first goal. + +Another useful construct is reduction, showing that a particular case +is in fact general enough to prove a general property. This kind of +reasoning step usually starts with: “Without loss of generality, we +can suppose that …”. Formally, this corresponds to the proof of a goal +``G`` by introducing a cut ``wlog_statement -> G``. Hence the user shall +provide a proof for both ``(wlog_statement -> G) -> G`` and +``wlog_statement -> G``. However, such cuts are usually rather +painful to perform by +hand, because the statement ``wlog_statement`` is tedious to write by hand, +and sometimes even to read. + +|SSR| implements this kind of reasoning step through the :tacn:`without loss` +tactic, whose short name is :tacn:`wlog`. It offers support to describe +the shape of the cut statements, by providing the simplifying +hypothesis and by pointing at the elements of the initial goals which +should be generalized. The general syntax of without loss is: + +.. tacn:: wlog {? suff } {? @clear_switch } {? @i_item } : {* @ident } / @term + without loss {? suff } {? @clear_switch } {? @i_item } : {* @ident } / @term + :name: wlog; without loss + :undocumented: + +where each :token:`ident` is a constant in the context +of the goal. Open syntax is supported for :token:`term`. + +In its defective form: + +.. tacv:: wlog: / @term + without loss: / @term + :undocumented: + +on a goal G, it creates two subgoals: a first one to prove the +formula (term -> G) -> G and a second one to prove the formula +term -> G. + +If the optional list of :token:`ident` is present +on the left side of ``/``, these constants are generalized in the +premise (term -> G) of the first subgoal. By default bodies of local +definitions are erased. This behavior can be inhibited by prefixing the +name of the local definition with the ``@`` character. + +In the second subgoal, the tactic: + +.. coqdoc:: + + move=> clear_switch i_item. + +is performed if at least one of these optional switches is present in +the :tacn:`wlog` tactic. + +The :tacn:`wlog` tactic is specially useful when a symmetry argument +simplifies a proof. Here is an example showing the beginning of the +proof that quotient and reminder of natural number euclidean division +are unique. + +.. example:: + + .. coqtop:: all + + Lemma quo_rem_unicity d q1 q2 r1 r2 : + q1*d + r1 = q2*d + r2 -> r1 < d -> r2 < d -> (q1, r1) = (q2, r2). + wlog: q1 q2 r1 r2 / q1 <= q2. + by case (le_gt_dec q1 q2)=> H; last symmetry; eauto with arith. + +The ``wlog suff`` variant is simpler, since it cuts ``wlog_statement`` instead +of ``wlog_statement -> G``. It thus opens the goals +``wlog_statement -> G`` +and ``wlog_statement``. + +In its simplest form the ``generally have : …`` tactic is equivalent to +``wlog suff : …`` followed by last first. When the ``have`` tactic is used +with the ``generally`` (or ``gen``) modifier it accepts an extra identifier +followed by a comma before the usual intro pattern. The identifier +will name the new hypothesis in its more general form, while the intro +pattern will be used to process its instance. + +.. example:: + + .. coqtop:: reset none + + From Coq Require Import ssreflect ssrfun ssrbool. + Set Implicit Arguments. + Unset Strict Implicit. + Unset Printing Implicit Defensive. + + Axiom P : nat -> Prop. + Axioms eqn leqn : nat -> nat -> bool. + Declare Scope this_scope. + Notation "a != b" := (eqn a b) (at level 70) : this_scope. + Notation "a <= b" := (leqn a b) (at level 70) : this_scope. + Open Scope this_scope. + + .. coqtop:: all + + Lemma simple n (ngt0 : 0 < n ) : P n. + gen have ltnV, /andP[nge0 neq0] : n ngt0 / (0 <= n) && (n != 0); last first. + + +.. _advanced_generalization_ssr: + +Advanced generalization ++++++++++++++++++++++++ + +The complete syntax for the items on the left hand side of the ``/`` +separator is the following one: + +.. tacv:: wlog … : {? @clear_switch | {? @ } @ident | ( {? @ } @ident := @c_pattern) } / @term + :undocumented: + +Clear operations are intertwined with generalization operations. This +helps in particular avoiding dependency issues while generalizing some +facts. + +If an :token:`ident` is prefixed with the ``@`` mark, then a let-in redex is +created, which keeps track if its body (if any). The syntax +``( ident := c_pattern)`` allows to generalize an arbitrary term using a +given name. Note that its simplest form ``(x := y)`` is just a renaming of +``y`` into ``x``. In particular, this can be useful in order to simulate the +generalization of a section variable, otherwise not allowed. Indeed +renaming does not require the original variable to be cleared. + +The syntax ``(@x := y)`` generates a let-in abstraction but with the +following caveat: ``x`` will not bind ``y``, but its body, whenever ``y`` can be +unfolded. This covers the case of both local and global definitions, as +illustrated in the following example. + +.. example:: + + .. coqtop:: reset none + + From Coq Require Import ssreflect. + Set Implicit Arguments. + Unset Strict Implicit. + Unset Printing Implicit Defensive. + + .. coqtop:: all + + Section Test. + Variable x : nat. + Definition addx z := z + x. + Lemma test : x <= addx x. + wlog H : (y := x) (@twoy := addx x) / twoy = 2 * y. + + To avoid unfolding the term captured by the pattern add x one can use + the pattern ``id (addx x)``, that would produce the following first + subgoal + + .. coqtop:: reset none + + From Coq Require Import ssreflect Omega. + Set Implicit Arguments. + Unset Strict Implicit. + Unset Printing Implicit Defensive. + + Section Test. + Variable x : nat. + Definition addx z := z + x. + Lemma test : x <= addx x. + + .. coqtop:: all + + wlog H : (y := x) (@twoy := id (addx x)) / twoy = 2 * y. + + +.. _rewriting_ssr: + +Rewriting +--------- + +The generalized use of reflection implies that most of the +intermediate results handled are properties of effectively computable +functions. The most efficient mean of establishing such results are +computation and simplification of expressions involving such +functions, i.e., rewriting. |SSR| therefore includes an +extended ``rewrite`` tactic, that unifies and combines most of the +rewriting functionalities. + + +An extended rewrite tactic +~~~~~~~~~~~~~~~~~~~~~~~~~~ + +The main features of the rewrite tactic are: + ++ It can perform an entire series of such operations in any subset of + the goal and/or context; ++ It allows to perform rewriting, simplifications, folding/unfolding + of definitions, closing of goals; ++ Several rewriting operations can be chained in a single tactic; ++ Control over the occurrence at which rewriting is to be performed is + significantly enhanced. + +The general form of an |SSR| rewrite tactic is: + +.. tacn:: rewrite {+ @rstep } + :name: rewrite (ssreflect) + :undocumented: + +The combination of a rewrite tactic with the ``in`` tactical (see section +:ref:`localization_ssr`) performs rewriting in both the context and the goal. + +A rewrite step :token:`rstep` has the general form: + +.. prodn:: + rstep ::= {? @r_prefix } @r_item + +.. prodn:: + r_prefix ::= {? - } {? @mult } {? @occ_switch %| @clear_switch } {? [ @r_pattern ] } + +.. prodn:: + r_pattern ::= @term %| in {? @ident in } @term %| %( @term in %| @term as %) @ident in @term + +.. prodn:: + r_item ::= {? / } @term %| @s_item + +An :token:`r_prefix` contains annotations to qualify where and how the rewrite +operation should be performed: + ++ The optional initial ``-`` indicates the direction of the rewriting of + :token:`r_item`: + if present the direction is right-to-left and it is left-to-right otherwise. ++ The multiplier :token:`mult` (see section :ref:`iteration_ssr`) + specifies if and how the + rewrite operation should be repeated. ++ A rewrite operation matches the occurrences of a *rewrite pattern*, + and replaces these occurrences by another term, according to the + given :token:`r_item`. The optional *redex switch* ``[r_pattern]``, + which should + always be surrounded by brackets, gives explicitly this rewrite + pattern. In its simplest form, it is a regular term. If no explicit + redex switch is present the rewrite pattern to be matched is inferred + from the :token:`r_item`. ++ This optional term, or the :token:`r_item`, may be preceded by an + :token:`occ_switch` (see section :ref:`selectors_ssr`) or a + :token:`clear_switch` (see section :ref:`discharge_ssr`), + these two possibilities being exclusive. + + An occurrence switch selects + the occurrences of the rewrite pattern which should be affected by the + rewrite operation. + + A clear switch, even an empty one, is performed *after* the + :token:`r_item` is actually processed and is complemented with the name of + the rewrite rule if an only if it is a simple proof context entry [#10]_. + As a consequence one can + write ``rewrite {}H`` to rewrite with ``H`` and dispose ``H`` immediately + afterwards. + This behavior can be avoided by putting parentheses around the rewrite rule. + +An :token:`r_item` can be: + + ++ A *simplification* :token:`r_item`, + represented by a :token:`s_item` (see section + :ref:`introduction_ssr`). Simplification operations are intertwined with the possible + other rewrite operations specified by the list of :token:`r_item`. ++ A *folding/unfolding* :token:`r_item`. The tactic: + ``rewrite /term`` unfolds the + head constant of term in every occurrence of the first matching of + term in the goal. In particular, if ``my_def`` is a (local or global) + defined constant, the tactic: ``rewrite /my_def.`` is analogous to: + ``unfold my_def``. + Conversely: ``rewrite -/my_def.`` is equivalent to: ``fold my_def``. + When an unfold :token:`r_item` is combined with a + redex pattern, a conversion + operation is performed. A tactic of the form: + ``rewrite -[term1]/term2.`` + is equivalent to: ``change term1 with term2.`` If ``term2`` is a + single constant and ``term1`` head symbol is not ``term2``, then the head + symbol of ``term1`` is repeatedly unfolded until ``term2`` appears. ++ A :token:`term`, which can be: + + A term whose type has the form: + ``forall (x1 : A1 )…(xn : An ), eq term1 term2`` where + ``eq`` is the Leibniz equality or a registered setoid + equality. + + A list of terms ``(t1 ,…,tn)``, each ``ti`` having a type above. + The tactic: ``rewrite r_prefix (t1 ,…,tn ).`` + is equivalent to: ``do [rewrite r_prefix t1 | … | rewrite r_prefix tn ].`` + + An anonymous rewrite lemma ``(_ : term)``, where term has a type as above. tactic: ``rewrite (_ : term)`` is in fact synonym of: ``cutrewrite (term).``. + + .. example:: + + .. coqtop:: reset none + + From Coq Require Import ssreflect. + Set Implicit Arguments. + Unset Strict Implicit. + Unset Printing Implicit Defensive. + + .. coqtop:: all abort + + Definition double x := x + x. + Definition ddouble x := double (double x). + Lemma test x : ddouble x = 4 * x. + rewrite [ddouble _]/double. + + .. warning:: + + The |SSR| terms containing holes are *not* typed as + abstractions in this context. Hence the following script fails. + + .. coqtop:: all + + Definition f := fun x y => x + y. + Lemma test x y : x + y = f y x. + + .. coqtop:: all fail + + rewrite -[f y]/(y + _). + + but the following script succeeds + + .. coqtop:: all + + rewrite -[f y x]/(y + _). + + +.. flag:: SsrOldRewriteGoalsOrder + + Controls the order in which generated subgoals (side conditions) + are added to the + proof context. The flag is off by default, which puts subgoals generated + by conditional rules first, followed by the main goal. When it is on, + the main goal appears first. If your proofs are organized to complete + proving the main goal before side conditions, turning the flag on will save you + from having to add :tacn:`last first` tactics that would be needed + to keep the main goal as the currently focused goal. + +Remarks and examples +~~~~~~~~~~~~~~~~~~~~ + +Rewrite redex selection +``````````````````````` + +The general strategy of |SSR| is to grasp as many redexes as +possible and to let the user select the ones to be rewritten thanks to +the improved syntax for the control of rewriting. + +This may be a source of incompatibilities between the two rewrite +tactics. + +In a rewrite tactic of the form: + +.. coqdoc:: + + rewrite occ_switch [term1]term2. + +``term1`` is the explicit rewrite redex and ``term2`` is the rewrite rule. +This execution of this tactic unfolds as follows: + + ++ First ``term1`` and ``term2`` are βι normalized. Then ``term2`` + is put in head + normal form if the Leibniz equality constructor ``eq`` is not the head + symbol. This may involve ζ reductions. ++ Then, the matching algorithm (see section :ref:`abbreviations_ssr`) + determines the + first subterm of the goal matching the rewrite pattern. The rewrite + pattern is given by ``term1``, if an explicit redex pattern switch is + provided, or by the type of ``term2`` otherwise. However, matching skips + over matches that would lead to trivial rewrites. All the occurrences + of this subterm in the goal are candidates for rewriting. ++ Then only the occurrences coded by :token:`occ_switch` (see again section + :ref:`abbreviations_ssr`) are finally selected for rewriting. ++ The left hand side of ``term2`` is unified with the subterm found by + the matching algorithm, and if this succeeds, all the selected + occurrences in the goal are replaced by the right hand side of ``term2``. ++ Finally the goal is βι normalized. + + +In the case ``term2`` is a list of terms, the first top-down (in the +goal) left-to-right (in the list) matching rule gets selected. + + +Chained rewrite steps +````````````````````` + +The possibility to chain rewrite operations in a single tactic makes +scripts more compact and gathers in a single command line a bunch of +surgical operations which would be described by a one sentence in a +pen and paper proof. + +Performing rewrite and simplification operations in a single tactic +enhances significantly the concision of scripts. For instance the +tactic: + +.. coqdoc:: + + rewrite /my_def {2}[f _]/= my_eq //=. + + +unfolds ``my_def`` in the goal, simplifies the second occurrence of the +first subterm matching pattern ``[f _]``, rewrites ``my_eq``, simplifies the +goals and closes trivial goals. + +Here are some concrete examples of chained rewrite operations, in the +proof of basic results on natural numbers arithmetic. + +.. example:: + + + .. coqtop:: reset none + + From Coq Require Import ssreflect. + Set Implicit Arguments. + Unset Strict Implicit. + Unset Printing Implicit Defensive. + + .. coqtop:: all + + Axiom addn0 : forall m, m + 0 = m. + Axiom addnS : forall m n, m + S n = S (m + n). + Axiom addSnnS : forall m n, S m + n = m + S n. + + Lemma addnCA m n p : m + (n + p) = n + (m + p). + by elim: m p => [ | m Hrec] p; rewrite ?addSnnS -?addnS. + Qed. + + Lemma addnC n m : m + n = n + m. + by rewrite -{1}[n]addn0 addnCA addn0. + Qed. + +Note the use of the ``?`` switch for parallel rewrite operations in the +proof of ``addnCA``. + + +Explicit redex switches are matched first +````````````````````````````````````````` + +If an :token:`r_prefix` involves a *redex switch*, the first step is to find a +subterm matching this redex pattern, independently from the left hand +side of the equality the user wants to rewrite. + + +.. example:: + + + .. coqtop:: reset none + + From Coq Require Import ssreflect. + Set Implicit Arguments. + Unset Strict Implicit. + Unset Printing Implicit Defensive. + + .. coqtop:: all + + Lemma test (H : forall t u, t + u = u + t) x y : x + y = y + x. + rewrite [y + _]H. + +Note that if this first pattern matching is not compatible with the +:token:`r_item`, the rewrite fails, even if the goal contains a +correct redex matching both the redex switch and the left hand side of +the equality. + +.. example:: + + + .. coqtop:: reset none + + From Coq Require Import ssreflect. + Set Implicit Arguments. + Unset Strict Implicit. + Unset Printing Implicit Defensive. + + .. coqtop:: all + + Lemma test (H : forall t u, t + u * 0 = t) x y : x + y * 4 + 2 * 0 = x + 2 * 0. + Fail rewrite [x + _]H. + + Indeed the left hand side of ``H`` does not match + the redex identified by the pattern ``x + y * 4``. + +.. _ssr_rewrite_occ_switch: + +Occurrence switches and redex switches +`````````````````````````````````````` + +.. example:: + + + .. coqtop:: reset none + + From Coq Require Import ssreflect. + Set Implicit Arguments. + Unset Strict Implicit. + Unset Printing Implicit Defensive. + + .. coqtop:: all + + Lemma test x y : x + y + 0 = x + y + y + 0 + 0 + (x + y + 0). + rewrite {2}[_ + y + 0](_: forall z, z + 0 = z). + +The second subgoal is generated by the use of an anonymous lemma in +the rewrite tactic. The effect of the tactic on the initial goal is to +rewrite this lemma at the second occurrence of the first matching +``x + y + 0`` of the explicit rewrite redex ``_ + y + 0``. + +Occurrence selection and repetition +``````````````````````````````````` + +Occurrence selection has priority over repetition switches. This means +the repetition of a rewrite tactic specified by a multiplier will +perform matching each time an elementary rewrite operation is +performed. Repeated rewrite tactics apply to every subgoal generated +by the previous tactic, including the previous instances of the +repetition. + +.. example:: + + .. coqtop:: reset none + + From Coq Require Import ssreflect. + Set Implicit Arguments. + Unset Strict Implicit. + Unset Printing Implicit Defensive. + + .. coqtop:: all + + Lemma test x y (z : nat) : x + 1 = x + y + 1. + rewrite 2!(_ : _ + 1 = z). + +This last tactic generates *three* subgoals because +the second rewrite operation specified with the ``2!`` multiplier +applies to the two subgoals generated by the first rewrite. + + +Multi-rule rewriting +```````````````````` + +The rewrite tactic can be provided a *tuple* of rewrite rules, or more +generally a tree of such rules, since this tuple can feature arbitrary +inner parentheses. We call *multirule* such a generalized rewrite +rule. This feature is of special interest when it is combined with +multiplier switches, which makes the rewrite tactic iterate the +rewrite operations prescribed by the rules on the current goal. + + +.. example:: + + .. coqtop:: reset none + + From Coq Require Import ssreflect. + Set Implicit Arguments. + Unset Strict Implicit. + Unset Printing Implicit Defensive. + + Section Test. + + .. coqtop:: all abort + + Variables (a b c : nat). + Hypothesis eqab : a = b. + Hypothesis eqac : a = c. + + Lemma test : a = a. + rewrite (eqab, eqac). + + Indeed rule ``eqab`` is the first to apply among the ones + gathered in the tuple passed to the rewrite tactic. This multirule + ``(eqab, eqac)`` is actually a |Coq| term and we can name it with a + definition: + + .. coqtop:: all + + Definition multi1 := (eqab, eqac). + + In this case, the tactic ``rewrite multi1`` is a synonym for + ``rewrite (eqab, eqac)``. + +More precisely, a multirule rewrites the first subterm to which one of +the rules applies in a left-to-right traversal of the goal, with the +first rule from the multirule tree in left-to-right order. Matching is +performed according to the algorithm described in +Section :ref:`abbreviations_ssr`, but +literal matches have priority. + +.. example:: + + .. coqtop:: all abort + + Definition d := a. + Hypotheses eqd0 : d = 0. + Definition multi2 := (eqab, eqd0). + + Lemma test : d = b. + rewrite multi2. + + Indeed rule ``eqd0`` applies without unfolding the + definition of ``d``. + +For repeated rewrites the selection process is +repeated anew. + +.. example:: + + .. coqtop:: all abort + + Hypothesis eq_adda_b : forall x, x + a = b. + Hypothesis eq_adda_c : forall x, x + a = c. + Hypothesis eqb0 : b = 0. + Definition multi3 := (eq_adda_b, eq_adda_c, eqb0). + + Lemma test : 1 + a = 12 + a. + rewrite 2!multi3. + + It uses ``eq_adda_b`` then ``eqb0`` on the left-hand + side only. Without the bound ``2`` one would obtain ``0 = 0``. + +The grouping of rules inside a multirule does not affect the selection +strategy but can make it easier to include one rule set in another or +to (universally) quantify over the parameters of a subset of rules (as +there is special code that will omit unnecessary quantifiers for rules +that can be syntactically extracted). It is also possible to reverse +the direction of a rule subset, using a special dedicated syntax: the +tactic rewrite ``(=~ multi1)`` is equivalent to ``rewrite multi1_rev``. + +.. example:: + + .. coqtop:: all + + Hypothesis eqba : b = a. + Hypothesis eqca : c = a. + Definition multi1_rev := (eqba, eqca). + +except that the constants ``eqba``, ``eqab``, ``mult1_rev`` +have not been created. + +Rewriting with multirules is useful to implement simplification or +transformation procedures, to be applied on terms of small to medium +size. For instance the library `ssrnat` (Mathematical Components library) +provides two implementations +for arithmetic operations on natural numbers: an elementary one and a +tail recursive version, less inefficient but also less convenient for +reasoning purposes. The library also provides one lemma per such +operation, stating that both versions return the same values when +applied to the same arguments: + +.. coqdoc:: + + Lemma addE : add =2 addn. + Lemma doubleE : double =1 doublen. + Lemma add_mulE n m s : add_mul n m s = addn (muln n m) s. + Lemma mulE : mul =2 muln. + Lemma mul_expE m n p : mul_exp m n p = muln (expn m n) p. + Lemma expE : exp =2 expn. + Lemma oddE : odd =1 oddn. + +The operation on the left hand side of each lemma is the efficient +version, and the corresponding naive implementation is on the right +hand side. In order to reason conveniently on expressions involving +the efficient operations, we gather all these rules in the definition +``trecE``: + +.. coqdoc:: + + Definition trecE := (addE, (doubleE, oddE), (mulE, add_mulE, (expE, mul_expE))). + +The tactic: ``rewrite !trecE.`` +restores the naive versions of each operation in a goal involving the +efficient ones, e.g. for the purpose of a correctness proof. + + +Wildcards vs abstractions +````````````````````````` + +The rewrite tactic supports :token:`r_items` containing holes. For example, in +the tactic ``rewrite (_ : _ * 0 = 0).`` +the term ``_ * 0 = 0`` is interpreted as ``forall n : nat, n * 0 = 0.`` +Anyway this tactic is *not* equivalent to +``rewrite (_ : forall x, x * 0 = 0).``. + +.. example:: + + .. coqtop:: reset none + + From Coq Require Import ssreflect. + Set Implicit Arguments. + Unset Strict Implicit. + Unset Printing Implicit Defensive. + + Section Test. + + .. coqtop:: all + + Lemma test y z : y * 0 + y * (z * 0) = 0. + rewrite (_ : _ * 0 = 0). + + while the other tactic results in + + .. coqtop:: all restart abort + + rewrite (_ : forall x, x * 0 = 0). + + The first tactic requires you to prove the instance of the (missing) + lemma that was used, while the latter requires you prove the quantified + form. + +When |SSR| rewrite fails on standard |Coq| licit rewrite +```````````````````````````````````````````````````````` + +In a few cases, the |SSR| rewrite tactic fails rewriting some +redexes which standard |Coq| successfully rewrites. There are two main +cases: + + ++ |SSR| never accepts to rewrite indeterminate patterns like: + + .. coqdoc:: + + Lemma foo (x : unit) : x = tt. + + |SSR| will however accept the + ηζ expansion of this rule: + + .. coqdoc:: + + Lemma fubar (x : unit) : (let u := x in u) = tt. + ++ The standard rewrite tactic provided by |Coq| uses a different algorithm + to find instances of the rewrite rule. + + .. example:: + + .. coqtop:: reset none + + From Coq Require Import ssreflect. + Set Implicit Arguments. + Unset Strict Implicit. + Unset Printing Implicit Defensive. + + Section Test. + + .. coqtop:: all + + Variable g : nat -> nat. + Definition f := g. + Axiom H : forall x, g x = 0. + + Lemma test : f 3 + f 3 = f 6. + (* we call the standard rewrite tactic here *) + rewrite -> H. + + This rewriting is not possible in |SSR| because + there is no occurrence of the head symbol ``f`` of the rewrite rule in the + goal. + + .. coqtop:: all restart fail + + rewrite H. + + Rewriting with ``H`` first requires unfolding the occurrences of + ``f`` + where the substitution is to be performed (here there is a single such + occurrence), using tactic ``rewrite /f`` (for a global replacement of + f by g) or ``rewrite pattern/f``, for a finer selection. + + .. coqtop:: all restart + + rewrite /f H. + + alternatively one can override the pattern inferred from ``H`` + + .. coqtop:: all restart + + rewrite [f _]H. + + +Existential metavariables and rewriting +``````````````````````````````````````` + +The rewrite tactic will not instantiate existing existential +metavariables when matching a redex pattern. + +If a rewrite rule generates a goal with new existential metavariables +in the ``Prop`` sort, these will be generalized as for ``apply`` +(see :ref:`apply_ssr`) and +corresponding new goals will be generated. + + +.. example:: + + .. coqtop:: reset none + + From Coq Require Import ssreflect ssrfun ssrbool. + Set Implicit Arguments. + Unset Strict Implicit. + Unset Printing Implicit Defensive. + Set Warnings "-notation-overridden". + + .. coqtop:: all abort + + Axiom leq : nat -> nat -> bool. + Notation "m <= n" := (leq m n) : nat_scope. + Notation "m < n" := (S m <= n) : nat_scope. + Inductive Ord n := Sub x of x < n. + Notation "'I_ n" := (Ord n) (at level 8, n at level 2, format "''I_' n"). + Arguments Sub {_} _ _. + Definition val n (i : 'I_n) := let: Sub a _ := i in a. + Definition insub n x := + if @idP (x < n) is ReflectT _ Px then Some (Sub x Px) else None. + Axiom insubT : forall n x Px, insub n x = Some (Sub x Px). + + Lemma test (x : 'I_2) y : Some x = insub 2 y. + rewrite insubT. + + Since the argument corresponding to Px is not supplied by the user, the + resulting goal should be ``Some x = Some (Sub y ?Goal).`` + Instead, |SSR| ``rewrite`` tactic hides the existential variable. + + As in :ref:`apply_ssr`, the ``ssrautoprop`` tactic is used to try to + solve the existential variable. + + .. coqtop:: all + + Lemma test (x : 'I_2) y (H : y < 2) : Some x = insub 2 y. + rewrite insubT. + + +As a temporary limitation, this behavior is available only if the +rewriting rule is stated using Leibniz equality (as opposed to setoid +relations). It will be extended to other rewriting relations in the +future. + + +.. _locking_ssr: + +Locking, unlocking +~~~~~~~~~~~~~~~~~~ + +As program proofs tend to generate large goals, it is important to be +able to control the partial evaluation performed by the simplification +operations that are performed by the tactics. These evaluations can +for example come from a ``/=`` simplification switch, or from rewrite +steps which may expand large terms while performing conversion. We +definitely want to avoid repeating large subterms of the goal in the +proof script. We do this by “clamping down” selected function symbols +in the goal, which prevents them from being considered in +simplification or rewriting steps. This clamping is accomplished by +using the occurrence switches (see section:ref:`abbreviations_ssr`) +together with “term tagging” operations. + +|SSR| provides two levels of tagging. + +The first one uses auxiliary definitions to introduce a provably equal +copy of any term t. However this copy is (on purpose) *not +convertible* to t in the |Coq| system [#8]_. The job is done by the +following construction: + +.. coqdoc:: + + Lemma master_key : unit. Proof. exact tt. Qed. + Definition locked A := let: tt := master_key in fun x : A => x. + Lemma lock : forall A x, x = locked x :> A. + +Note that the definition of *master_key* is explicitly opaque. The +equation ``t = locked t`` given by the ``lock`` lemma can be used for +selective rewriting, blocking on the fly the reduction in the term ``t``. + +.. example:: + + .. coqtop:: reset none + + From Coq Require Import ssreflect ssrfun ssrbool. + From Coq Require Import List. + Set Implicit Arguments. + Unset Strict Implicit. + Unset Printing Implicit Defensive. + Section Test. + + .. coqtop:: all + + Variable A : Type. + Fixpoint has (p : A -> bool) (l : list A) : bool := + if l is cons x l then p x || (has p l) else false. + + Lemma test p x y l (H : p x = true) : has p ( x :: y :: l) = true. + rewrite {2}[cons]lock /= -lock. + +It is sometimes desirable to globally prevent a definition from being +expanded by simplification; this is done by adding locked in the +definition. + +.. example:: + + .. coqtop:: reset none + + From Coq Require Import ssreflect. + Set Implicit Arguments. + Unset Strict Implicit. + Unset Printing Implicit Defensive. + Section Test. + + .. coqtop:: all + + Definition lid := locked (fun x : nat => x). + + Lemma test : lid 3 = 3. + rewrite /=. + unlock lid. + +.. tacn:: unlock {? @occ_switch } @ident + :name: unlock + + This tactic unfolds such definitions while removing “locks”, i.e. it + replaces the occurrence(s) of :token:`ident` coded by the + :token:`occ_switch` with the corresponding body. + +We found that it was usually preferable to prevent the expansion of +some functions by the partial evaluation switch ``/=``, unless this +allowed the evaluation of a condition. This is possible thanks to another +mechanism of term tagging, resting on the following *Notation*: + +.. coqdoc:: + + Notation "'nosimpl' t" := (let: tt := tt in t). + +The term ``(nosimpl t)`` simplifies to ``t`` *except* in a definition. +More precisely, given: + +.. coqdoc:: + + Definition foo := (nosimpl bar). + +the term ``foo`` (or ``(foo t’)``) will *not* be expanded by the *simpl* +tactic unless it is in a forcing context (e.g., in ``match foo t’ with … +end``, ``foo t’`` will be reduced if this allows ``match`` to be reduced). +Note that ``nosimpl bar`` is simply notation for a term that reduces to +``bar``; hence ``unfold foo`` will replace ``foo`` by ``bar``, and +``fold foo`` will replace ``bar`` by ``foo``. + +.. warning:: + + The ``nosimpl`` trick only works if no reduction is apparent in + ``t``; in particular, the declaration: + + .. coqdoc:: + + Definition foo x := nosimpl (bar x). + + will usually not work. Anyway, the common practice is to tag only the + function, and to use the following definition, which blocks the + reduction as expected: + + .. coqdoc:: + + Definition foo x := nosimpl bar x. + +A standard example making this technique shine is the case of +arithmetic operations. We define for instance: + +.. coqdoc:: + + Definition addn := nosimpl plus. + +The operation ``addn`` behaves exactly like ``plus``, except that +``(addn (S n) m)`` will not simplify spontaneously to +``(S (addn n m))`` (the two terms, however, are convertible). +In addition, the unfolding step: ``rewrite /addn`` +will replace ``addn`` directly with ``plus``, so the ``nosimpl`` form is +essentially invisible. + + +.. _congruence_ssr: + +Congruence +~~~~~~~~~~ + +Because of the way matching interferes with parameters of type families, +the tactic: + +.. coqdoc:: + + apply: my_congr_property. + +will generally fail to perform congruence simplification, even on +rather simple cases. We therefore provide a more robust alternative in +which the function is supplied: + +.. tacn:: congr {? @num } @term + :name: congr + + This tactic: + + checks that the goal is a Leibniz equality; + + matches both sides of this equality with “term applied to some arguments”, inferring the right number of arguments from the goal and the type of term. This may expand some definitions or fixpoints; + + generates the subgoals corresponding to pairwise equalities of the arguments present in the goal. + + The goal can be a non dependent product ``P -> Q``. In that case, the + system asserts the equation ``P = Q``, uses it to solve the goal, and + calls the ``congr`` tactic on the remaining goal ``P = Q``. This can be useful + for instance to perform a transitivity step, like in the following + situation. + + .. example:: + + .. coqtop:: reset none + + From Coq Require Import ssreflect. + Set Implicit Arguments. + Unset Strict Implicit. + Unset Printing Implicit Defensive. + Section Test. + + .. coqtop:: all + + Lemma test (x y z : nat) (H : x = y) : x = z. + congr (_ = _) : H. + Abort. + + Lemma test (x y z : nat) : x = y -> x = z. + congr (_ = _). + + The optional :token:`num` forces the number of arguments for which the + tactic should generate equality proof obligations. + + This tactic supports equalities between applications with dependent + arguments. Yet dependent arguments should have exactly the same + parameters on both sides, and these parameters should appear as first + arguments. + + .. example:: + + .. coqtop:: reset none + + From Coq Require Import ssreflect. + Set Implicit Arguments. + Unset Strict Implicit. + Unset Printing Implicit Defensive. + Section Test. + + .. coqtop:: all + + Definition f n := + if n is 0 then plus else mult. + Definition g (n m : nat) := plus. + + Lemma test x y : f 0 x y = g 1 1 x y. + congr plus. + + This script shows that the ``congr`` tactic matches ``plus`` + with ``f 0`` on the left hand side and ``g 1 1`` on the right hand + side, and solves the goal. + + .. example:: + + .. coqtop:: reset none + + From Coq Require Import ssreflect. + Set Implicit Arguments. + Unset Strict Implicit. + Unset Printing Implicit Defensive. + Section Test. + + .. coqtop:: all + + Lemma test n m (Hnm : m <= n) : S m + (S n - S m) = S n. + congr S; rewrite -/plus. + + The tactic ``rewrite -/plus`` folds back the expansion of plus + which was necessary for matching both sides of the equality with + an application of ``S``. + + Like most |SSR| arguments, :token:`term` can contain wildcards. + + .. example:: + + .. coqtop:: reset none + + From Coq Require Import ssreflect. + Set Implicit Arguments. + Unset Strict Implicit. + Unset Printing Implicit Defensive. + Section Test. + + .. coqtop:: all + + Lemma test x y : x + (y * (y + x - x)) = x * 1 + (y + 0) * y. + congr ( _ + (_ * _)). + +.. _contextual_patterns_ssr: + +Contextual patterns +------------------- + +The simple form of patterns used so far, terms possibly containing +wild cards, often require an additional :token:`occ_switch` to be specified. +While this may work pretty fine for small goals, the use of +polymorphic functions and dependent types may lead to an invisible +duplication of function arguments. These copies usually end up in +types hidden by the implicit arguments machinery or by user-defined +notations. In these situations computing the right occurrence numbers +is very tedious because they must be counted on the goal as printed +after setting the :flag:`Printing All` flag. Moreover the resulting script is +not really informative for the reader, since it refers to occurrence +numbers he cannot easily see. + +Contextual patterns mitigate these issues allowing to specify +occurrences according to the context they occur in. + + +Syntax +~~~~~~ + +The following table summarizes the full syntax of :token:`c_pattern` and the +corresponding subterm(s) identified by the pattern. In the third +column we use s.m.r. for “the subterms matching the redex” specified +in the second column. + +.. list-table:: + :header-rows: 1 + + * - :token:`c_pattern` + - redex + - subterms affected + + * - ``term`` + - ``term`` + - all occurrences of ``term`` + + * - ``ident in term`` + - subterm of ``term`` selected by ``ident`` + - all the subterms identified by ``ident`` in all the + occurrences of ``term`` + + * - ``term1 in ident in term2`` + - ``term1`` in all s.m.r. + - in all the subterms identified by + ``ident`` in all the occurrences of ``term2`` + * - ``term1 as ident in term2`` + - ``term 1`` + - in all the subterms identified by ``ident` + in all the occurrences of ``term2[term 1 /ident]`` + +The rewrite tactic supports two more patterns obtained prefixing the +first two with in. The intended meaning is that the pattern identifies +all subterms of the specified context. The ``rewrite`` tactic will infer a +pattern for the redex looking at the rule used for rewriting. + +.. list-table:: + :header-rows: 1 + + * - :token:`r_pattern` + - redex + - subterms affected + + * - ``in term`` + - inferred from rule + - in all s.m.r. in all occurrences of ``term`` + + * - ``in ident in term`` + - inferred from rule + - in all s.m.r. in all the subterms identified by ``ident`` + in all the occurrences of ``term`` + +The first :token:`c_pattern` is the simplest form matching any context but +selecting a specific redex and has been described in the previous +sections. We have seen so far that the possibility of selecting a +redex using a term with holes is already a powerful means of redex +selection. Similarly, any terms provided by the user in the more +complex forms of :token:`c_patterns` +presented in the tables above can contain +holes. + +For a quick glance at what can be expressed with the last +:token:`r_pattern` +consider the goal ``a = b`` and the tactic + +.. coqdoc:: + + rewrite [in X in _ = X]rule. + +It rewrites all occurrences of the left hand side of ``rule`` +inside ``b`` only (``a``, and the hidden type of the equality, are ignored). Note that the +variant ``rewrite [X in _ = X]rule`` would have rewritten ``b`` +exactly (i.e., it would only work if ``b`` and the left hand side +of rule can be unified). + + +Matching contextual patterns +~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +The :token:`c_pattern` and :token:`r_pattern` involving terms +with holes are matched +against the goal in order to find a closed instantiation. This +matching proceeds as follows: + +.. list-table:: + :header-rows: 1 + + * - :token:`c_pattern` + - instantiation order and place for ``term_i`` and redex + + * - ``term`` + - ``term`` is matched against the goal, redex is unified with + the instantiation of ``term`` + + * - ``ident in term`` + - ``term`` is matched against the goal, redex is unified with the + subterm of the instantiation of ``term`` identified by + ``ident`` + + * - ``term1 in ident in term2`` + - ``term2`` is matched against the goal, ``term1`` + is matched against the subterm of the instantiation of + ``term1`` identified by ``ident``, redex is unified with + the instantiation of ``term1`` + + * - ``term1 as ident in term2`` + - ``term2[term1/ident]`` is matched against + the goal, redex is unified with the instantiation of ``term1`` + +In the following patterns, the redex is intended to be inferred from +the rewrite rule. + +.. list-table:: + :header-rows: 1 + + * - :token:`r_pattern` + - instantiation order and place for ``term_i`` and redex + + * - ``in ident in term`` + - ``term`` is matched against the goal, the redex is matched against + the subterm of the instantiation of ``term`` identified by + ``ident`` + + * - ``in term`` + - ``term`` is matched against the goal, redex is matched against the + instantiation of ``term`` + + +Examples +~~~~~~~~ + + +Contextual pattern in set and the : tactical +```````````````````````````````````````````` + +As already mentioned in section :ref:`abbreviations_ssr` the ``set`` +tactic takes as an +argument a term in open syntax. This term is interpreted as the +simplest form of :token:`c_pattern`. To avoid confusion in the grammar, open +syntax is supported only for the simplest form of patterns, while +parentheses are required around more complex patterns. + +.. example:: + + .. coqtop:: reset none + + From Coq Require Import ssreflect. + Set Implicit Arguments. + Unset Strict Implicit. + Unset Printing Implicit Defensive. + Section Test. + + .. coqtop:: all + + Lemma test a b : a + b + 1 = b + (a + 1). + set t := (X in _ = X). + rewrite {}/t. + set t := (a + _ in X in _ = X). + + +Since the user may define an infix notation for ``in`` the result of the former +tactic may be ambiguous. The disambiguation rule implemented is to prefer +patterns over simple terms, but to interpret a pattern with double +parentheses as a simple term. For example, the following tactic would +capture any occurrence of the term ``a in A``. + +.. coqdoc:: + + set t := ((a in A)). + +Contextual patterns can also be used as arguments of the ``:`` tactical. +For example: + +.. coqdoc:: + + elim: n (n in _ = n) (refl_equal n). + + +Contextual patterns in rewrite +`````````````````````````````` + +.. example:: + + .. coqtop:: reset none + + From Coq Require Import ssreflect. + Set Implicit Arguments. + Unset Strict Implicit. + Unset Printing Implicit Defensive. + Section Test. + + .. coqtop:: all + + Notation "n .+1" := (Datatypes.S n) (at level 2, left associativity, + format "n .+1") : nat_scope. + + Axiom addSn : forall m n, m.+1 + n = (m + n).+1. + Axiom addn0 : forall m, m + 0 = m. + Axiom addnC : forall m n, m + n = n + m. + + Lemma test x y z f : (x.+1 + y) + f (x.+1 + y) (z + (x + y).+1) = 0. + rewrite [in f _ _]addSn. + + Note: the simplification rule ``addSn`` is applied only under the ``f`` + symbol. + Then we simplify also the first addition and expand 0 into 0+0. + + .. coqtop:: all + + rewrite addSn -[X in _ = X]addn0. + + Note that the right hand side of ``addn0`` is undetermined, but the + rewrite pattern specifies the redex explicitly. The right hand side + of ``addn0`` is unified with the term identified by ``X``, here ``0``. + + + The following pattern does not specify a redex, since it identifies an + entire region, hence the rewrite rule has to be instantiated + explicitly. Thus the tactic: + + .. coqtop:: all + + rewrite -{2}[in X in _ = X](addn0 0). + + The following tactic is quite tricky: + + .. coqtop:: all + + rewrite [_.+1 in X in f _ X](addnC x.+1). + + The explicit redex ``_.+1`` is important since its head constant ``S`` + differs from the head constant inferred from + ``(addnC x.+1)`` (that is ``+``). + Moreover, the pattern ``f _ X`` is important to rule out + the first occurrence of ``(x + y).+1``. + Last, only the subterms of ``f _ X`` + identified by ``X`` are rewritten, thus the first argument of + ``f`` is skipped too. + Also note the pattern ``_.+1`` is interpreted in the context + identified by ``X``, thus it gets instantiated to + ``(y + x).+1`` and not ``(x + y).+1``. + + The last rewrite pattern allows to specify exactly the shape of the + term identified by X, that is thus unified with the left hand side of + the rewrite rule. + + .. coqtop:: all + + rewrite [x.+1 + y as X in f X _]addnC. + + +Patterns for recurrent contexts +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +The user can define shortcuts for recurrent contexts corresponding to +the ``ident in term`` part. The notation scope identified with +``%pattern`` +provides a special notation ``(X in t)`` the user must adopt +in order to define +context shortcuts. + +The following example is taken from ``ssreflect.v`` where the +``LHS`` and ``RHS`` shortcuts are defined. + +.. coqdoc:: + + Notation RHS := (X in _ = X)%pattern. + Notation LHS := (X in X = _)%pattern. + +Shortcuts defined this way can be freely used in place of the trailing +``ident in term`` part of any contextual pattern. Some examples follow: + +.. coqdoc:: + + set rhs := RHS. + rewrite [in RHS]rule. + case: (a + _ in RHS). + + +.. _views_and_reflection_ssr: + +Views and reflection +-------------------- + +The bookkeeping facilities presented in section :ref:`basic_tactics_ssr` are +crafted to ease simultaneous introductions and generalizations of facts and +operations of casing, naming etc. It also a common practice to make a stack +operation immediately followed by an *interpretation* of the fact +being pushed, that is, to apply a lemma to this fact before passing it +to a tactic for decomposition, application and so on. + +|SSR| provides a convenient, unified syntax to combine these +interpretation operations with the proof stack operations. This *view +mechanism* relies on the combination of the ``/`` view switch with +bookkeeping tactics and tacticals. + +.. _custom_elim_ssr: + +Interpreting eliminations +~~~~~~~~~~~~~~~~~~~~~~~~~ + +The view syntax combined with the ``elim`` tactic specifies an elimination +scheme to be used instead of the default, generated, one. Hence the +|SSR| tactic: + +.. coqdoc:: + + elim/V. + +is a synonym for: + +.. coqdoc:: + + intro top; elim top using V; clear top. + +where top is a fresh name and V any second-order lemma. + +Since an elimination view supports the two bookkeeping tacticals of +discharge and introduction (see section :ref:`basic_tactics_ssr`), +the |SSR| tactic: + +.. coqdoc:: + + elim/V: x => y. + +is a synonym for: + +.. coqdoc:: + + elim x using V; clear x; intro y. + +where ``x`` is a variable in the context, ``y`` a fresh name and ``V`` +any second order lemma; |SSR| relaxes the syntactic restrictions of the |Coq| +``elim``. The first pattern following ``:`` can be a ``_`` wildcard if the +conclusion of the view ``V`` specifies a pattern for its last argument +(e.g., if ``V`` is a functional induction lemma generated by the +``Function`` command). + +The elimination view mechanism is compatible with the equation name +generation (see section :ref:`generation_of_equations_ssr`). + + +.. example:: + + The following script illustrates a toy example of this feature. Let us + define a function adding an element at the end of a list: + + .. coqtop:: reset none + + From Coq Require Import ssreflect List. + Set Implicit Arguments. + Unset Strict Implicit. + Unset Printing Implicit Defensive. + Section Test. + + .. coqtop:: all + + Variable d : Type. + Fixpoint add_last (s : list d) (z : d) {struct s} : list d := + if s is cons x s' then cons x (add_last s' z) else z :: nil. + + One can define an alternative, reversed, induction principle on + inductively defined lists, by proving the following lemma: + + .. coqtop:: all + + Axiom last_ind_list : forall P : list d -> Prop, + P nil -> (forall s (x : d), P s -> P (add_last s x)) -> + forall s : list d, P s. + + Then the combination of elimination views with equation names result + in a concise syntax for reasoning inductively using the user-defined + elimination scheme. + + .. coqtop:: all + + Lemma test (x : d) (l : list d): l = l. + elim/last_ind_list E : l=> [| u v]; last first. + + +User-provided eliminators (potentially generated with |Coq|’s ``Function`` +command) can be combined with the type family switches described +in section :ref:`type_families_ssr`. +Consider an eliminator ``foo_ind`` of type: + +.. coqdoc:: + + foo_ind : forall …, forall x : T, P p1 … pm. + +and consider the tactic: + +.. coqdoc:: + + elim/foo_ind: e1 … / en. + +The ``elim/`` tactic distinguishes two cases: + +:truncated eliminator: when ``x`` does not occur in ``P p1 … pm`` and the + type of ``en`` unifies with ``T`` and ``en`` is not ``_``. + In that case, ``en`` is + passed to the eliminator as the last argument (``x`` in ``foo_ind``) and + ``en−1 … e1`` are used as patterns to select in the goal the occurrences that + will be bound by the predicate ``P``, thus it must be possible to unify + the sub-term of the goal matched by ``en−1`` with ``pm`` , the one matched + by ``en−2`` with ``pm−1`` and so on. +:regular eliminator: in all the other cases. Here it must be possible + to unify the term matched by ``en`` with ``pm`` , the one matched by + ``en−1`` + with ``pm−1`` and so on. Note that standard eliminators have the shape + ``…forall x, P … x``, thus ``en`` is the pattern identifying the + eliminated term, as expected. + + +As explained in section :ref:`type_families_ssr`, the initial prefix of +``ei`` can be omitted. + +Here is an example of a regular, but nontrivial, eliminator. + +.. example:: + + Here is a toy example illustrating this feature. + + .. coqtop:: reset none + + From Coq Require Import ssreflect FunInd. + Set Implicit Arguments. + Unset Strict Implicit. + Unset Printing Implicit Defensive. + Section Test. + + .. coqtop:: all + + Function plus (m n : nat) {struct n} : nat := + if n is S p then S (plus m p) else m. + + About plus_ind. + + Lemma test x y z : plus (plus x y) z = plus x (plus y z). + + The following tactics are all valid and perform the same elimination + on this goal. + + .. coqdoc:: + + elim/plus_ind: z / (plus _ z). + elim/plus_ind: {z}(plus _ z). + elim/plus_ind: {z}_. + elim/plus_ind: z / _. + + .. coqtop:: reset none + + From Coq Require Import ssreflect FunInd. + Set Implicit Arguments. + Unset Strict Implicit. + Unset Printing Implicit Defensive. + Section Test. + + Function plus (m n : nat) {struct n} : nat := + if n is S p then S (plus m p) else m. + + About plus_ind. + + Lemma test x y z : plus (plus x y) z = plus x (plus y z). + + .. coqtop:: all + + elim/plus_ind: z / _. + + The two latter examples feature a wildcard pattern: in this case, + the resulting pattern is inferred from the type of the eliminator. + In both these examples, it is ``(plus _ _)``, which matches the subterm + ``plus (plus x y) z`` thus instantiating the last ``_`` with ``z``. + Note that the tactic: + + .. coqtop:: reset none + + From Coq Require Import ssreflect FunInd. + Set Implicit Arguments. + Unset Strict Implicit. + Unset Printing Implicit Defensive. + Section Test. + + Function plus (m n : nat) {struct n} : nat := + if n is S p then S (plus m p) else m. + + About plus_ind. + + Lemma test x y z : plus (plus x y) z = plus x (plus y z). + + .. coqtop:: all + + Fail elim/plus_ind: y / _. + + triggers an error: in the conclusion + of the ``plus_ind`` eliminator, the first argument of the predicate + ``P`` should be the same as the second argument of ``plus``, in the + second argument of ``P``, but ``y`` and ``z`` do no unify. + +Here is an example of a truncated eliminator: + +.. example:: + + Consider the goal: + + .. coqtop:: reset none + + From Coq Require Import ssreflect FunInd. + Set Implicit Arguments. + Unset Strict Implicit. + Unset Printing Implicit Defensive. + Section Test. + + .. coqdoc:: + + Lemma test p n (n_gt0 : 0 < n) (pr_p : prime p) : + p %| \prod_(i <- prime_decomp n | i \in prime_decomp n) i.1 ^ i.2 -> + exists2 x : nat * nat, x \in prime_decomp n & p = x.1. + Proof. + elim/big_prop: _ => [| u v IHu IHv | [q e] /=]. + + + where the type of the ``big_prop`` eliminator is + + .. coqdoc:: + + big_prop: forall (R : Type) (Pb : R -> Type) + (idx : R) (op1 : R -> R -> R), Pb idx -> + (forall x y : R, Pb x -> Pb y -> Pb (op1 x y)) -> + forall (I : Type) (r : seq I) (P : pred I) (F : I -> R), + (forall i : I, P i -> Pb (F i)) -> + Pb (\big[op1/idx]_(i <- r | P i) F i). + + Since the pattern for the argument of Pb is not specified, the + inferred one is used instead: ``big[_/_]_(i <- _ | _ i) _ i``, + and after the introductions, the following goals are generated: + + .. coqdoc:: + + subgoal 1 is: + p %| 1 -> exists2 x : nat * nat, x \in prime_decomp n & p = x.1 + subgoal 2 is: + p %| u * v -> exists2 x : nat * nat, x \in prime_decomp n & p = x.1 + subgoal 3 is: + (q, e) \in prime_decomp n -> p %| q ^ e -> + exists2 x : nat * nat, x \in prime_decomp n & p = x.1. + + Note that the pattern matching algorithm instantiated all the + variables occurring in the pattern. + + +.. _interpreting_assumptions_ssr: + +Interpreting assumptions +~~~~~~~~~~~~~~~~~~~~~~~~ + +Interpreting an assumption in the context of a proof consists in +applying to it a lemma before generalizing, and/or decomposing this +assumption. For instance, with the extensive use of boolean reflection +(see section :ref:`views_and_reflection_ssr`.4), it is quite frequent +to need to decompose the logical interpretation of (the boolean +expression of) a fact, rather than the fact itself. This can be +achieved by a combination of ``move : _ => _`` switches, like in the +following example, where ``||`` is a notation for the boolean +disjunction. + + +.. example:: + + .. coqtop:: reset none + + From Coq Require Import ssreflect. + Set Implicit Arguments. + Unset Strict Implicit. + Unset Printing Implicit Defensive. + Section Test. + + .. coqtop:: all + + Variables P Q : bool -> Prop. + Hypothesis P2Q : forall a b, P (a || b) -> Q a. + + Lemma test a : P (a || a) -> True. + move=> HPa; move: {HPa}(P2Q HPa) => HQa. + + which transforms the hypothesis ``HPa : P a`` which has been introduced + from the initial statement into ``HQa : Q a``. + This operation is so common that the tactic shell has specific + syntax for it. The following scripts: + + .. coqtop:: reset none + + From Coq Require Import ssreflect. + Set Implicit Arguments. + Unset Strict Implicit. + Unset Printing Implicit Defensive. + Section Test. + + Variables P Q : bool -> Prop. + Hypothesis P2Q : forall a b, P (a || b) -> Q a. + + Lemma test a : P (a || a) -> True. + + .. coqtop:: all + + move=> HPa; move/P2Q: HPa => HQa. + + or more directly: + + .. coqtop:: all restart + + move/P2Q=> HQa. + + are equivalent to the former one. The former script shows how to + interpret a fact (already in the context), thanks to the discharge + tactical (see section :ref:`discharge_ssr`) and the latter, how to interpret the top + assumption of a goal. Note that the number of wildcards to be inserted + to find the correct application of the view lemma to the hypothesis + has been automatically inferred. + +The view mechanism is compatible with the ``case`` tactic and with the +equation name generation mechanism (see section :ref:`generation_of_equations_ssr`): + +.. example:: + + .. coqtop:: reset none + + From Coq Require Import ssreflect. + Set Implicit Arguments. + Unset Strict Implicit. + Unset Printing Implicit Defensive. + Section Test. + + .. coqtop:: all + + Variables P Q: bool -> Prop. + Hypothesis Q2P : forall a b, Q (a || b) -> P a \/ P b. + + Lemma test a b : Q (a || b) -> True. + case/Q2P=> [HPa | HPb]. + + This view tactic performs: + + .. coqdoc:: + + move=> HQ; case: {HQ}(Q2P HQ) => [HPa | HPb]. + +The term on the right of the ``/`` view switch is called a *view lemma*. +Any |SSR| term coercing to a product type can be used as a view +lemma. + +The examples we have given so far explicitly provide the direction of +the translation to be performed. In fact, view lemmas need not to be +oriented. The view mechanism is able to detect which application is +relevant for the current goal. + +.. example:: + + .. coqtop:: reset none + + From Coq Require Import ssreflect. + Set Implicit Arguments. + Unset Strict Implicit. + Unset Printing Implicit Defensive. + Section Test. + + .. coqtop:: all + + Variables P Q: bool -> Prop. + Hypothesis PQequiv : forall a b, P (a || b) <-> Q a. + + Lemma test a b : P (a || b) -> True. + move/PQequiv=> HQab. + + has the same behavior as the first example above. + + The view mechanism can insert automatically a *view hint* to transform + the double implication into the expected simple implication. The last + script is in fact equivalent to: + + .. coqdoc:: + + Lemma test a b : P (a || b) -> True. + move/(iffLR (PQequiv _ _)). + + where: + + .. coqdoc:: + + Lemma iffLR P Q : (P <-> Q) -> P -> Q. + + +Specializing assumptions +```````````````````````` + +The special case when the *head symbol* of the view lemma is a +wildcard is used to interpret an assumption by *specializing* it. The +view mechanism hence offers the possibility to apply a higher-order +assumption to some given arguments. + +.. example:: + + .. coqtop:: reset none + + From Coq Require Import ssreflect. + Set Implicit Arguments. + Unset Strict Implicit. + Unset Printing Implicit Defensive. + Section Test. + + .. coqtop:: all + + Lemma test z : (forall x y, x + y = z -> z = x) -> z = 0. + move/(_ 0 z). + + +Interpreting goals +~~~~~~~~~~~~~~~~~~ + +In a similar way, it is also often convenient to +changing a goal by turning it into an equivalent proposition. The view +mechanism of |SSR| has a special syntax ``apply/`` for combining in a +single tactic simultaneous goal interpretation operations and +bookkeeping steps. + + +.. example:: + + The following example use the ``~~`` prenex notation for boolean negation: + + + .. coqtop:: reset none + + From Coq Require Import ssreflect ssrbool. + Set Implicit Arguments. + Unset Strict Implicit. + Unset Printing Implicit Defensive. + Section Test. + + .. coqtop:: all + + Variables P Q: bool -> Prop. + Hypothesis PQequiv : forall a b, P (a || b) <-> Q a. + + Lemma test a : P ((~~ a) || a). + apply/PQequiv. + + thus in this case, the tactic ``apply/PQequiv`` is equivalent to + ``apply: (iffRL (PQequiv _ _))``, where ``iffRL`` is tha analogue of + ``iffRL`` for the converse implication. + +Any |SSR| term whose type coerces to a double implication can be +used as a view for goal interpretation. + +Note that the goal interpretation view mechanism supports both ``apply`` +and ``exact`` tactics. As expected, a goal interpretation view command +exact/term should solve the current goal or it will fail. + +.. warning:: + + Goal interpretation view tactics are *not* compatible with + the bookkeeping tactical ``=>`` since this would be redundant with the + ``apply: term => _`` construction. + + +Boolean reflection +~~~~~~~~~~~~~~~~~~ + +In the Calculus of Inductive Constructions, there is an obvious +distinction between logical propositions and boolean values. On the +one hand, logical propositions are objects of *sort* ``Prop`` which is +the carrier of intuitionistic reasoning. Logical connectives in +``Prop`` are *types*, which give precise information on the structure +of their proofs; this information is automatically exploited by |Coq| +tactics. For example, |Coq| knows that a proof of ``A \/ B`` is +either a proof of ``A`` or a proof of ``B``. The tactics ``left`` and +``right`` change the goal ``A \/ B`` to ``A`` and ``B``, respectively; +dually, the tactic ``case`` reduces the goal ``A \/ B => G`` to two +subgoals ``A => G`` and ``B => G``. + +On the other hand, bool is an inductive *datatype* with two +constructors true and false. Logical connectives on bool are +*computable functions*, defined by their truth tables, using case +analysis: + +.. example:: + + .. coqtop:: reset none + + From Coq Require Import ssreflect. + Set Implicit Arguments. + Unset Strict Implicit. + Unset Printing Implicit Defensive. + Section Test. + + .. coqtop:: all + + Definition orb (b1 b2 : bool) := if b1 then true else b2. + +Properties of such connectives are also established using case +analysis + +.. example:: + + .. coqtop:: reset none + + From Coq Require Import ssreflect ssrbool. + Set Implicit Arguments. + Unset Strict Implicit. + Unset Printing Implicit Defensive. + Section Test. + + .. coqtop:: all + + Lemma test b : b || ~~ b = true. + by case: b. + + Once ``b`` is replaced by ``true`` in the first goal and by ``false`` in the + second one, the goals reduce by computations to the trivial ``true = true``. + +Thus, ``Prop`` and ``bool`` are truly complementary: the former supports +robust natural deduction, the latter allows brute-force +evaluation. |SSR| supplies a generic mechanism to have the best of +the two worlds and move freely from a propositional version of a +decidable predicate to its boolean version. + +First, booleans are injected into propositions using the coercion +mechanism: + +.. coqdoc:: + + Coercion is_true (b : bool) := b = true. + +This allows any boolean formula ``b`` to be used in a context where |Coq| +would expect a proposition, e.g., after ``Lemma … : ``. It is then +interpreted as ``(is_true b)``, i.e., the proposition ``b = true``. Coercions +are elided by the pretty-printer, so they are essentially transparent +to the user. + +The reflect predicate +~~~~~~~~~~~~~~~~~~~~~ + +To get all the benefits of the boolean reflection, it is in fact +convenient to introduce the following inductive predicate ``reflect`` to +relate propositions and booleans: + +.. coqdoc:: + + Inductive reflect (P: Prop): bool -> Type := + | Reflect_true : P -> reflect P true + | Reflect_false : ~P -> reflect P false. + +The statement ``(reflect P b)`` asserts that ``(is_true b)`` and ``P`` are +logically equivalent propositions. + +For instance, the following lemma: + +.. coqdoc:: + + Lemma andP: forall b1 b2, reflect (b1 /\ b2) (b1 && b2). + +relates the boolean conjunction to the logical one ``/\``. Note that in +``andP``, ``b1`` and ``b2`` are two boolean variables and the +proposition ``b1 /\ b2`` hides two coercions. The conjunction of +``b1`` and ``b2`` can then be viewed as ``b1 /\ b2`` or as ``b1 && b2``. + +Expressing logical equivalences through this family of inductive types +makes possible to take benefit from *rewritable equations* associated +to the case analysis of |Coq|’s inductive types. + +Since the equivalence predicate is defined in |Coq| as: + +.. coqdoc:: + + Definition iff (A B:Prop) := (A -> B) /\ (B -> A). + +where ``/\`` is a notation for ``and``: + +.. coqdoc:: + + Inductive and (A B:Prop) : Prop := conj : A -> B -> and A B. + +This make case analysis very different according to the way an +equivalence property has been defined. + +.. coqdoc:: + + Lemma andE (b1 b2 : bool) : (b1 /\ b2) <-> (b1 && b2). + +Let us compare the respective behaviors of ``andE`` and ``andP``. + + +.. example:: + + .. coqtop:: reset none + + From Coq Require Import ssreflect ssrbool. + Set Implicit Arguments. + Unset Strict Implicit. + Unset Printing Implicit Defensive. + Section Test. + Axiom andE : forall (b1 b2 : bool), (b1 /\ b2) <-> (b1 && b2). + + .. coqtop:: all + + Lemma test (b1 b2 : bool) : if (b1 && b2) then b1 else ~~(b1||b2). + + .. coqtop:: all + + case: (@andE b1 b2). + + .. coqtop:: none + + Restart. + + .. coqtop:: all + + case: (@andP b1 b2). + +Expressing reflection relation through the ``reflect`` predicate is hence +a very convenient way to deal with classical reasoning, by case +analysis. Using the ``reflect`` predicate allows moreover to program rich +specifications inside its two constructors, which will be +automatically taken into account during destruction. This +formalisation style gives far more efficient specifications than +quantified (double) implications. + +A naming convention in |SSR| is to postfix the name of view lemmas +with ``P``. For example, ``orP`` relates ``||`` and ``\/``, +``negP`` relates ``~~`` and ``~``. + +The view mechanism is compatible with reflect predicates. + +.. example:: + + .. coqtop:: reset none + + From Coq Require Import ssreflect ssrbool. + Set Implicit Arguments. + Unset Strict Implicit. + Unset Printing Implicit Defensive. + Section Test. + + .. coqtop:: all abort + + Lemma test (a b : bool) (Ha : a) (Hb : b) : a /\ b. + apply/andP. + + Conversely + + .. coqtop:: all + + Lemma test (a b : bool) : a /\ b -> a. + move/andP. + +The same tactics can also be used to perform the converse operation, +changing a boolean conjunction into a logical one. The view mechanism +guesses the direction of the transformation to be used i.e., the +constructor of the reflect predicate which should be chosen. + + +General mechanism for interpreting goals and assumptions +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Specializing assumptions +```````````````````````` + +The |SSR| tactic: + +.. coqdoc:: + + move/(_ term1 … termn). + +is equivalent to the tactic: + +.. coqdoc:: + + intro top; generalize (top term1 … termn); clear top. + +where ``top`` is a fresh name for introducing the top assumption of the +current goal. + + +Interpreting assumptions +```````````````````````` + +The general form of an assumption view tactic is: + +.. tacv:: [move | case] / @term + :undocumented: + +The term , called the *view lemma* can be: + + ++ a (term coercible to a) function; ++ a (possibly quantified) implication; ++ a (possibly quantified) double implication; ++ a (possibly quantified) instance of the reflect predicate (see + section :ref:`views_and_reflection_ssr`). + + +Let ``top`` be the top assumption in the goal. + +There are three steps in the behavior of an assumption view tactic: + ++ It first introduces ``top``. ++ If the type of :token:`term` is neither a double implication nor an + instance of the reflect predicate, then the tactic automatically + generalises a term of the form: ``term term1 … termn`` where the + terms ``term1 … termn`` instantiate the possible quantified variables of + ``term`` , in order for ``(term term1 … termn top)`` to be well typed. ++ If the type of ``term`` is an equivalence, or an instance of the + reflect predicate, it generalises a term of the form: + ``(termvh (term term1 … termn ))`` where the term ``termvh`` + inserted is called an + *assumption interpretation view hint*. ++ It finally clears top. + + +For a ``case/term`` tactic, the generalisation step is replaced by a +case analysis step. + +*View hints* are declared by the user (see section:ref:`views_and_reflection_ssr`.8) and are +stored in the Hint View database. The proof engine automatically +detects from the shape of the top assumption ``top`` and of the view lemma +``term`` provided to the tactic the appropriate view hint in the +database to be inserted. + +If ``term`` is a double implication, then the view hint will be one of +the defined view hints for implication. These hints are by default the +ones present in the file ``ssreflect.v``: + +.. coqdoc:: + + Lemma iffLR : forall P Q, (P <-> Q) -> P -> Q. + +which transforms a double implication into the left-to-right one, or: + +.. coqdoc:: + + Lemma iffRL : forall P Q, (P <-> Q) -> Q -> P. + +which produces the converse implication. In both cases, the two +first Prop arguments are implicit. + +If ``term`` is an instance of the ``reflect`` predicate, then ``A`` will be one +of the defined view hints for the ``reflect`` predicate, which are by +default the ones present in the file ``ssrbool.v``. These hints are not +only used for choosing the appropriate direction of the translation, +but they also allow complex transformation, involving negations. + +.. example:: + + .. coqtop:: reset none + + From Coq Require Import ssreflect ssrbool. + Set Implicit Arguments. + Unset Strict Implicit. + Unset Printing Implicit Defensive. + Section Test. + + .. coqtop:: all + + Check introN. + + .. coqtop:: all + + Lemma test (a b : bool) (Ha : a) (Hb : b) : ~~ (a && b). + apply/andP. + + In fact this last script does not + exactly use the hint ``introN``, but the more general hint: + + .. coqtop:: all + + Check introNTF. + + The lemma ``introN`` is an instantiation of ``introNF`` using ``c := true``. + +Note that views, being part of :token:`i_pattern`, can be used to interpret +assertions too. For example the following script asserts ``a && b`` but +actually uses its propositional interpretation. + + +.. example:: + + .. coqtop:: reset none + + From Coq Require Import ssreflect ssrbool. + Set Implicit Arguments. + Unset Strict Implicit. + Unset Printing Implicit Defensive. + Section Test. + + .. coqtop:: all + + Lemma test (a b : bool) (pab : b && a) : b. + have /andP [pa ->] : (a && b) by rewrite andbC. + +Interpreting goals + +A goal interpretation view tactic of the form: + +.. tacv:: apply/@term + :undocumented: + +applied to a goal ``top`` is interpreted in the following way: + ++ If the type of ``term`` is not an instance of the ``reflect`` predicate, + nor an equivalence, then the term ``term`` is applied to the current + goal ``top``, possibly inserting implicit arguments. ++ If the type of ``term`` is an instance of the reflect predicate or an + equivalence, then a *goal interpretation view hint* can possibly be + inserted, which corresponds to the application of a term + ``(termvh (term _ … _))`` to the current goal, possibly inserting implicit arguments. + + +Like assumption interpretation view hints, goal interpretation ones +are user-defined lemmas stored (see section :ref:`views_and_reflection_ssr`) in the ``Hint View`` +database bridging the possible gap between the type of ``term`` and the +type of the goal. + + +Interpreting equivalences +~~~~~~~~~~~~~~~~~~~~~~~~~ + +Equivalent boolean propositions are simply *equal* boolean terms. A +special construction helps the user to prove boolean equalities by +considering them as logical double implications (between their coerced +versions), while performing at the same time logical operations on +both sides. + +The syntax of double views is: + +.. tacv:: apply/@term/@term + :undocumented: + +The first term is the view lemma applied to the left hand side of the +equality, while the second term is the one applied to the right hand side. + +In this context, the identity view can be used when no view has to be applied: + +.. coqdoc:: + + Lemma idP : reflect b1 b1. + +.. example:: + + .. coqtop:: reset none + + From Coq Require Import ssreflect ssrbool. + Set Implicit Arguments. + Unset Strict Implicit. + Unset Printing Implicit Defensive. + Section Test. + + .. coqtop:: all + + Lemma test (b1 b2 b3 : bool) : ~~ (b1 || b2) = b3. + apply/idP/idP. + + The same goal can be decomposed in several ways, and the user may + choose the most convenient interpretation. + + .. coqtop:: reset none + + From Coq Require Import ssreflect ssrbool. + Set Implicit Arguments. + Unset Strict Implicit. + Unset Printing Implicit Defensive. + Section Test. + + .. coqtop:: all + + Lemma test (b1 b2 b3 : bool) : ~~ (b1 || b2) = b3. + apply/norP/idP. + + +.. _declaring_new_hints_ssr: + +Declaring new Hint Views +~~~~~~~~~~~~~~~~~~~~~~~~ + +.. cmd:: Hint View for move / @ident {? | @num } + Hint View for apply / @ident {? | @num } + + This command can be used to extend the database of hints for the view + mechanism. + + As library ``ssrbool.v`` already declares a + corpus of hints, this feature is probably useful only for users who + define their own logical connectives. + + The :token:`ident` is the name of the lemma to be + declared as a hint. If ``move`` is used as + tactic, the hint is declared for assumption interpretation tactics, + ``apply`` declares hints for goal interpretations. Goal interpretation + view hints are declared for both simple views and left hand side + views. The optional natural number is the number of implicit + arguments to be considered for the declared hint view lemma. + + .. cmdv:: Hint View for apply//@ident {? | @num } + + This variant with a double slash ``//``, declares hint views for right + hand sides of double views. + + See the files ``ssreflect.v`` and ``ssrbool.v`` for examples. + + +Multiple views +~~~~~~~~~~~~~~ + +The hypotheses and the goal can be interpreted by applying multiple views +in sequence. Both move and apply can be followed by an arbitrary +number of ``/term``. The main difference between the following two +tactics + +.. coqdoc:: + + apply/v1/v2/v3. + apply/v1; apply/v2; apply/v3. + +is that the former applies all the views to the principal goal. +Applying a view with hypotheses generates new goals, and the second +line would apply the view ``v2`` to all the goals generated by ``apply/v1``. + +Note that the NO-OP intro pattern ``-`` can be used to separate two views, +making the two following examples equivalent: + +.. coqdoc:: + + move=> /v1; move=> /v2. + move=> /v1 - /v2. + +The tactic ``move`` can be used together with the ``in`` tactical to +pass a given hypothesis to a lemma. + + +.. example:: + + .. coqtop:: reset none + + From Coq Require Import ssreflect ssrbool. + Set Implicit Arguments. + Unset Strict Implicit. + Unset Printing Implicit Defensive. + Section Test. + Variables P Q R : Prop. + + .. coqtop:: all + + Variable P2Q : P -> Q. + Variable Q2R : Q -> R. + + Lemma test (p : P) : True. + move/P2Q/Q2R in p. + +If the list of views is of length two, ``Hint Views`` for interpreting +equivalences are indeed taken into account, otherwise only single +``Hint Views`` are used. + + +|SSR| searching tool +-------------------- + +.. cmd:: Search {? @pattern } {* {? - } %( @string %| @pattern %) {? % @ident} } {? in {+ {? - } @qualid } } + :name: Search (ssreflect) + + This is the |SSR| extension of the Search command. :token:`qualid` is the + name of an open module. This command returns the list of lemmas: + + + whose *conclusion* contains a subterm matching the optional first + pattern. A - reverses the test, producing the list of lemmas whose + conclusion does not contain any subterm matching the pattern; + + whose name contains the given string. A ``-`` prefix reverses the test, + producing the list of lemmas whose name does not contain the string. A + string that contains symbols or is followed by a scope key, is + interpreted as the constant whose notation involves that string (e.g., + :g:`+` for :g:`addn`), if this is unambiguous; otherwise the diagnostic + includes the output of the :cmd:`Locate` vernacular command. + + whose statement, including assumptions and types, contains a subterm + matching the next patterns. If a pattern is prefixed by ``-``, the test is + reversed; + + contained in the given list of modules, except the ones in the + modules prefixed by a ``-``. + +.. note:: + + + As for regular terms, patterns can feature scope indications. For + instance, the command: ``Search _ (_ + _)%N.`` lists all the lemmas whose + statement (conclusion or hypotheses) involves an application of the + binary operation denoted by the infix ``+`` symbol in the ``N`` scope (which is + |SSR| scope for natural numbers). + + Patterns with holes should be surrounded by parentheses. + + Search always volunteers the expansion of the notation, avoiding the + need to execute Locate independently. Moreover, a string fragment + looks for any notation that contains fragment as a substring. If the + ``ssrbool.v`` library is imported, the command: ``Search "~~".`` answers : + + .. coqtop:: reset none + + From Coq Require Import ssreflect ssrbool. + Set Implicit Arguments. + Unset Strict Implicit. + Unset Printing Implicit Defensive. + + .. coqtop:: all + + Search "~~". + + + A diagnostic is issued if there are different matching notations; it + is an error if all matches are partial. + + Similarly, a diagnostic warns about multiple interpretations, and + signals an error if there is no default one. + + The command ``Search in M.`` is a way of obtaining the complete + signature of the module ``M``. + + Strings and pattern indications can be interleaved, but the first + indication has a special status if it is a pattern, and only filters + the conclusion of lemmas: + + + The command : ``Search (_ =1 _) "bij".`` lists all the lemmas whose + conclusion features a ``=1`` and whose name contains the string ``bij``. + + The command : ``Search "bij" (_ =1 _).`` lists all the lemmas whose + statement, including hypotheses, features a ``=1`` and whose name + contains the string ``bij``. + +Synopsis and Index +------------------ + +Parameters +~~~~~~~~~~ + +|SSR| tactics + +.. prodn:: + d_tactic ::= elim %| case %| congr %| apply %| exact %| move + +Notation scope + +.. prodn:: key ::= @ident + +Module name + +.. prodn:: modname ::= @qualid + +Natural number + +.. prodn:: natural ::= @num %| @ident + +where :token:`ident` is an Ltac variable denoting a standard |Coq| numeral +(should not be the name of a tactic which can be followed by a +bracket ``[``, like ``do``, ``have``,…) + +Items and switches +~~~~~~~~~~~~~~~~~~ + +.. prodn:: ssr_binder ::= @ident %| ( @ident {? : @term } ) + +binder see :ref:`abbreviations_ssr`. + +.. prodn:: clear_switch ::= { {+ @ident } } + +clear switch see :ref:`discharge_ssr` + +.. prodn:: c_pattern ::= {? @term in %| @term as } @ident in @term + +context pattern see :ref:`contextual_patterns_ssr` + +.. prodn:: d_item ::= {? @occ_switch %| @clear_switch } {? @term %| ( @c_pattern ) } + +discharge item see :ref:`discharge_ssr` + +.. prodn:: gen_item ::= {? @ } @ident %| ( @ident ) %| ( {? @ } @ident := @c_pattern ) + +generalization item see :ref:`structure_ssr` + +.. prodn:: i_pattern ::= @ident %| > %| _ %| ? %| * %| + %| {? @occ_switch } -> %| {? @occ_switch } <- %| [ {?| @i_item } ] %| - %| [: {+ @ident } ] + +intro pattern :ref:`introduction_ssr` + +.. prodn:: i_item ::= @clear_switch %| @s_item %| @i_pattern %| @i_view %| @i_block + +view :ref:`introduction_ssr` + +.. prodn:: + i_view ::= {? %{%} } /@term %| /ltac:( @tactic ) + +intro block :ref:`introduction_ssr` + +.. prodn:: + i_block ::= [^ @ident ] %| [^~ @ident ] %| [^~ @num ] + +intro item see :ref:`introduction_ssr` + +.. prodn:: int_mult ::= {? @num } @mult_mark + +multiplier see :ref:`iteration_ssr` + +.. prodn:: occ_switch ::= { {? + %| - } {* @num } } + +occur. switch see :ref:`occurrence_selection_ssr` + +.. prodn:: mult ::= {? @num } @mult_mark + +multiplier see :ref:`iteration_ssr` + +.. prodn:: mult_mark ::= ? %| ! + +multiplier mark see :ref:`iteration_ssr` + +.. prodn:: r_item ::= {? / } @term %| @s_item + +rewrite item see :ref:`rewriting_ssr` + +.. prodn:: r_prefix ::= {? - } {? @int_mult } {? @occ_switch %| @clear_switch } {? [ @r_pattern ] } + +rewrite prefix see :ref:`rewriting_ssr` + +.. prodn:: r_pattern ::= @term %| @c_pattern %| in {? @ident in } @term + +rewrite pattern see :ref:`rewriting_ssr` + +.. prodn:: r_step ::= {? @r_prefix } @r_item + +rewrite step see :ref:`rewriting_ssr` + +.. prodn:: s_item ::= /= %| // %| //= + +simplify switch see :ref:`introduction_ssr` + +Tactics +~~~~~~~ + +*Note*: ``without loss`` and ``suffices`` are synonyms for ``wlog`` and ``suff`` +respectively. + +.. tacn:: move + + :tacn:`idtac` or :tacn:`hnf` (see :ref:`bookkeeping_ssr`) + +.. tacn:: apply + exact + + application (see :ref:`the_defective_tactics_ssr`) + +.. tacn:: abstract + + see :ref:`abstract_ssr` and :ref:`generating_let_ssr` + +.. tacn:: elim + + induction (see :ref:`the_defective_tactics_ssr`) + +.. tacn:: case + + case analysis (see :ref:`the_defective_tactics_ssr`) + +.. tacn:: rewrite {+ @r_step } + + rewrite (see :ref:`rewriting_ssr`) + +.. tacn:: have {* @i_item } {? @i_pattern } {? @s_item %| {+ @ssr_binder } } {? : @term } := @term + have {* @i_item } {? @i_pattern } {? @s_item %| {+ @ssr_binder } } : @term {? by @tactic } + have suff {? @clear_switch } {? @i_pattern } {? : @term } := @term + have suff {? @clear_switch } {? @i_pattern } : @term {? by @tactic } + gen have {? @ident , } {? @i_pattern } : {+ @gen_item } / @term {? by @tactic } + generally have {? @ident , } {? @i_pattern } : {+ @gen_item } / @term {? by @tactic } + :name: _; _; _; _; _; generally have + + forward chaining (see :ref:`structure_ssr`) + +.. tacn:: wlog {? suff } {? @i_item } : {* @gen_item %| @clear_switch } / @term + + specializing (see :ref:`structure_ssr`) + +.. tacn:: suff {* @i_item } {? @i_pattern } {+ @ssr_binder } : @term {? by @tactic } + suffices {* @i_item } {? @i_pattern } {+ @ssr_binder } : @term {? by @tactic } + suff {? have } {? @clear_switch } {? @i_pattern } : @term {? by @tactic } + suffices {? have } {? @clear_switch } {? @i_pattern } : @term {? by @tactic } + :name: suff; suffices; _; _ + + backchaining (see :ref:`structure_ssr`) + +.. tacn:: pose @ident := @term + + local definition (see :ref:`definitions_ssr`) + +.. tacv:: pose @ident {+ @ssr_binder } := @term + + local function definition + +.. tacv:: pose fix @fix_body + + local fix definition + +.. tacv:: pose cofix @fix_body + + local cofix definition + +.. tacn:: set @ident {? : @term } := {? @occ_switch } %( @term %| ( @c_pattern) %) + + abbreviation (see :ref:`abbreviations_ssr`) + +.. tacn:: unlock {* {? @r_prefix } @ident } + + unlock (see :ref:`locking_ssr`) + +.. tacn:: congr {? @num } @term + + congruence (see :ref:`congruence_ssr`) + + +Tacticals +~~~~~~~~~ + +.. prodn:: tactic += @d_tactic {? @ident } : {+ @d_item } {? @clear_switch } + +discharge :ref:`discharge_ssr` + +.. prodn:: tactic += @tactic => {+ @i_item } + +introduction see :ref:`introduction_ssr` + +.. prodn:: tactic += @tactic in {+ @gen_item %| @clear_switch } {? * } + +localization see :ref:`localization_ssr` + +.. prodn:: tactic += do {? @mult } %( @tactic %| [ {+| @tactic } ] %) + +iteration see :ref:`iteration_ssr` + +.. prodn:: tactic += @tactic ; %( first %| last %) {? @num } %( @tactic %| [ {+| @tactic } ] %) + +selector see :ref:`selectors_ssr` + +.. prodn:: tactic += @tactic ; %( first %| last %) {? @num } + +rotation see :ref:`selectors_ssr` + +.. prodn:: tactic += by %( @tactic %| [ {*| @tactic } ] %) + +closing see :ref:`terminators_ssr` + +Commands +~~~~~~~~ + +.. cmd:: Hint View for %( move %| apply %) / @ident {? | @num } + + view hint declaration (see :ref:`declaring_new_hints_ssr`) + +.. cmd:: Hint View for apply // @ident {? @num } + + right hand side double , view hint declaration (see :ref:`declaring_new_hints_ssr`) + +.. cmd:: Prenex Implicits {+ @ident } + + prenex implicits declaration (see :ref:`parametric_polymorphism_ssr`) + +Settings +~~~~~~~~ + +.. flag:: Debug Ssreflect + + *Developer only.* Print debug information on reflect. + +.. flag:: Debug SsrMatching + + *Developer only.* Print debug information on SSR matching. + +.. rubric:: Footnotes + +.. [#1] Unfortunately, even after a call to the Set Printing All command, + some occurrences are still not displayed to the user, essentially the + ones possibly hidden in the predicate of a dependent match structure. +.. [#2] Thus scripts that depend on bound variable names, e.g., via intros + or with, are inherently fragile. +.. [#3] The name ``subnK`` reads as “right cancellation rule for nat + subtraction”. +.. [#4] Also, a slightly different variant may be used for the first :token:`d_item` + of case and elim; see section :ref:`type_families_ssr`. +.. [#5] Except /= does not expand the local definitions created by the + |SSR| in tactical. +.. [#6] |SSR| reserves all identifiers of the form “_x_”, which is + used for such generated names. +.. [#7] More precisely, it should have a quantified inductive type with a + assumptions and m − a constructors. +.. [#8] This is an implementation feature: there is no such obstruction + in the metatheory +.. [#9] The current state of the proof shall be displayed by the Show + Proof command of |Coq| proof mode. +.. [#10] A simple proof context entry is a naked identifier (i.e. not between + parentheses) designating a context entry that is not a section variable. diff --git a/doc/sphinx/proof-engine/tactics.rst b/doc/sphinx/proof-engine/tactics.rst new file mode 100644 index 0000000000..afb0239be4 --- /dev/null +++ b/doc/sphinx/proof-engine/tactics.rst @@ -0,0 +1,4807 @@ +.. _tactics: + +Tactics +======== + +A deduction rule is a link between some (unique) formula, that we call +the *conclusion* and (several) formulas that we call the *premises*. A +deduction rule can be read in two ways. The first one says: “if I know +this and this then I can deduce this”. For instance, if I have a proof +of A and a proof of B then I have a proof of A ∧ B. This is forward +reasoning from premises to conclusion. The other way says: “to prove +this I have to prove this and this”. For instance, to prove A ∧ B, I +have to prove A and I have to prove B. This is backward reasoning from +conclusion to premises. We say that the conclusion is the *goal* to +prove and premises are the *subgoals*. The tactics implement *backward +reasoning*. When applied to a goal, a tactic replaces this goal with +the subgoals it generates. We say that a tactic reduces a goal to its +subgoal(s). + +Each (sub)goal is denoted with a number. The current goal is numbered +1. By default, a tactic is applied to the current goal, but one can +address a particular goal in the list by writing n:tactic which means +“apply tactic tactic to goal number n”. We can show the list of +subgoals by typing Show (see Section :ref:`requestinginformation`). + +Since not every rule applies to a given statement, not every tactic can +be used to reduce a given goal. In other words, before applying a tactic +to a given goal, the system checks that some *preconditions* are +satisfied. If it is not the case, the tactic raises an error message. + +Tactics are built from atomic tactics and tactic expressions (which +extends the folklore notion of tactical) to combine those atomic +tactics. This chapter is devoted to atomic tactics. The tactic +language will be described in Chapter :ref:`ltac`. + +Common elements of tactics +-------------------------- + +.. _invocation-of-tactics: + +Invocation of tactics +~~~~~~~~~~~~~~~~~~~~~ + +A tactic is applied as an ordinary command. It may be preceded by a +goal selector (see Section :ref:`ltac-semantics`). If no selector is +specified, the default selector is used. + +.. _tactic_invocation_grammar: + + .. productionlist:: sentence + tactic_invocation : `toplevel_selector` : `tactic`. + : `tactic`. + +.. opt:: Default Goal Selector "@toplevel_selector" + :name: Default Goal Selector + + This option controls the default selector, used when no selector is + specified when applying a tactic. The initial value is 1, hence the + tactics are, by default, applied to the first goal. + + Using value ``all`` will make it so that tactics are, by default, + applied to every goal simultaneously. Then, to apply a tactic tac + to the first goal only, you can write ``1:tac``. + + Using value ``!`` enforces that all tactics are used either on a + single focused goal or with a local selector (’’strict focusing + mode’’). + + Although more selectors are available, only ``all``, ``!`` or a + single natural number are valid default goal selectors. + +.. _bindingslist: + +Bindings list +~~~~~~~~~~~~~~~~~~~ + +Tactics that take a term as an argument may also support a bindings list +to instantiate some parameters of the term by name or position. +The general form of a term with a bindings list is +:n:`@term with @bindings_list` where :token:`bindings_list` can take two different forms: + +.. _bindings_list_grammar: + + .. productionlist:: bindings_list + ref : `ident` + : `num` + bindings_list : (`ref` := `term`) ... (`ref` := `term`) + : `term` ... `term` + ++ In a bindings list of the form :n:`{+ (@ref:= @term)}`, :n:`@ref` is either an + :n:`@ident` or a :n:`@num`. The references are determined according to the type of + :n:`@term`. If :n:`@ref` is an identifier, this identifier has to be bound in the + type of :n:`@term` and the binding provides the tactic with an instance for the + parameter of this name. If :n:`@ref` is a number ``n``, it refers to + the ``n``-th non dependent premise of the :n:`@term`, as determined by the type + of :n:`@term`. + + .. exn:: No such binder. + :undocumented: + ++ A bindings list can also be a simple list of terms :n:`{* @term}`. + In that case the references to which these terms correspond are + determined by the tactic. In case of :tacn:`induction`, :tacn:`destruct`, :tacn:`elim` + and :tacn:`case`, the terms have to + provide instances for all the dependent products in the type of term while in + the case of :tacn:`apply`, or of :tacn:`constructor` and its variants, only instances + for the dependent products that are not bound in the conclusion of the type + are required. + + .. exn:: Not the right number of missing arguments. + :undocumented: + +.. _intropatterns: + +Intro patterns +~~~~~~~~~~~~~~ + +Intro patterns let you specify the name to assign to variables and hypotheses +introduced by tactics. They also let you split an introduced hypothesis into +multiple hypotheses or subgoals. Common tactics that accept intro patterns +include :tacn:`assert`, :tacn:`intros` and :tacn:`destruct`. + +.. productionlist:: coq + intropattern_list : `intropattern` ... `intropattern` + : `empty` + empty : + intropattern : * + : ** + : `simple_intropattern` + simple_intropattern : `simple_intropattern_closed` [ % `term` ... % `term` ] + simple_intropattern_closed : `naming_intropattern` + : _ + : `or_and_intropattern` + : `equality_intropattern` + naming_intropattern : `ident` + : ? + : ?`ident` + or_and_intropattern : [ `intropattern_list` | ... | `intropattern_list` ] + : ( `simple_intropattern` , ... , `simple_intropattern` ) + : ( `simple_intropattern` & ... & `simple_intropattern` ) + equality_intropattern : -> + : <- + : [= `intropattern_list` ] + or_and_intropattern_loc : `or_and_intropattern` + : `ident` + +Note that the intro pattern syntax varies between tactics. +Most tactics use :n:`@simple_intropattern` in the grammar. +:tacn:`destruct`, :tacn:`edestruct`, :tacn:`induction`, +:tacn:`einduction`, :tacn:`case`, :tacn:`ecase` and the various +:tacn:`inversion` tactics use :n:`@or_and_intropattern_loc`, while +:tacn:`intros` and :tacn:`eintros` use :n:`@intropattern_list`. +The :n:`eqn:` construct in various tactics uses :n:`@naming_intropattern`. + +**Naming patterns** + +Use these elementary patterns to specify a name: + +* :n:`@ident` - use the specified name +* :n:`?` - let Coq choose a name +* :n:`?@ident` - generate a name that begins with :n:`@ident` +* :n:`_` - discard the matched part (unless it is required for another + hypothesis) +* if a disjunction pattern omits a name, such as :g:`[|H2]`, Coq will choose a name + +**Splitting patterns** + +The most common splitting patterns are: + +* split a hypothesis in the form :n:`A /\ B` into two + hypotheses :g:`H1: A` and :g:`H2: B` using the pattern :g:`(H1 & H2)` or + :g:`(H1, H2)` or :g:`[H1 H2]`. + :ref:`Example <intropattern_conj_ex>`. This also works on :n:`A <-> B`, which + is just a notation representing :n:`(A -> B) /\ (B -> A)`. +* split a hypothesis in the form :g:`A \/ B` into two + subgoals using the pattern :g:`[H1|H2]`. The first subgoal will have the hypothesis + :g:`H1: A` and the second subgoal will have the hypothesis :g:`H2: B`. + :ref:`Example <intropattern_disj_ex>` +* split a hypothesis in either of the forms :g:`A /\ B` or :g:`A \/ B` using the pattern :g:`[]`. + +Patterns can be nested: :n:`[[Ha|Hb] H]` can be used to split :n:`(A \/ B) /\ C`. + +Note that there is no equivalent to intro patterns for goals. For a goal :g:`A /\ B`, +use the :tacn:`split` tactic to replace the current goal with subgoals :g:`A` and :g:`B`. +For a goal :g:`A \/ B`, use :tacn:`left` to replace the current goal with :g:`A`, or +:tacn:`right` to replace the current goal with :g:`B`. + +* :n:`( {+, @simple_intropattern}` ) - matches + a product over an inductive type with a + :ref:`single constructor <intropattern_cons_note>`. + If the number of patterns + equals the number of constructor arguments, then it applies the patterns only to + the arguments, and + :n:`( {+, @simple_intropattern} )` is equivalent to :n:`[{+ @simple_intropattern}]`. + If the number of patterns equals the number of constructor arguments plus the number + of :n:`let-ins`, the patterns are applied to the arguments and :n:`let-in` variables. + +* :n:`( {+& @simple_intropattern} )` - matches a right-hand nested term that consists + of one or more nested binary inductive types such as :g:`a1 OP1 a2 OP2 ...` + (where the :g:`OPn` are right-associative). + (If the :g:`OPn` are left-associative, additional parentheses will be needed to make the + term right-hand nested, such as :g:`a1 OP1 (a2 OP2 ...)`.) + The splitting pattern can have more than 2 names, for example :g:`(H1 & H2 & H3)` + matches :g:`A /\ B /\ C`. + The inductive types must have a + :ref:`single constructor with two parameters <intropattern_cons_note>`. + :ref:`Example <intropattern_ampersand_ex>` + +* :n:`[ {+| @intropattern_list} ]` - splits an inductive type that has + :ref:`multiple constructors <intropattern_cons_note>` + such as :n:`A \/ B` + into multiple subgoals. The number of :token:`intropattern_list` must be the same as the number of + constructors for the matched part. +* :n:`[ {+ @intropattern} ]` - splits an inductive type that has a + :ref:`single constructor with multiple parameters <intropattern_cons_note>` + such as :n:`A /\ B` into multiple hypotheses. Use :n:`[H1 [H2 H3]]` to match :g:`A /\ B /\ C`. +* :n:`[]` - splits an inductive type: If the inductive + type has multiple constructors, such as :n:`A \/ B`, + create one subgoal for each constructor. If the inductive type has a single constructor with + multiple parameters, such as :n:`A /\ B`, split it into multiple hypotheses. + +**Equality patterns** + +These patterns can be used when the hypothesis is an equality: + +* :n:`->` - replaces the right-hand side of the hypothesis with the left-hand + side of the hypothesis in the conclusion of the goal; the hypothesis is + cleared; if the left-hand side of the hypothesis is a variable, it is + substituted everywhere in the context and the variable is removed. + :ref:`Example <intropattern_rarrow_ex>` +* :n:`<-` - similar to :n:`->`, but replaces the left-hand side of the hypothesis + with the right-hand side of the hypothesis. +* :n:`[= {*, @intropattern} ]` - If the product is over an equality type, + applies either :tacn:`injection` or :tacn:`discriminate`. + If :tacn:`injection` is applicable, the intropattern + is used on the hypotheses generated by :tacn:`injection`. If the + number of patterns is smaller than the number of hypotheses generated, the + pattern :n:`?` is used to complete the list. + :ref:`Example <intropattern_inj_discr_ex>` + +**Other patterns** + +* :n:`*` - introduces one or more quantified variables from the result + until there are no more quantified variables. + :ref:`Example <intropattern_star_ex>` + +* :n:`**` - introduces one or more quantified variables or hypotheses from the result until there are + no more quantified variables or implications (:g:`->`). :g:`intros **` is equivalent + to :g:`intros`. + :ref:`Example <intropattern_2stars_ex>` + +* :n:`@simple_intropattern_closed {* % @term}` - first applies each of the terms + with the :tacn:`apply ... in` tactic on the hypothesis to be introduced, then it uses + :n:`@simple_intropattern_closed`. + :ref:`Example <intropattern_injection_ex>` + +.. flag:: Bracketing Last Introduction Pattern + + For :n:`intros @intropattern_list`, controls how to handle a + conjunctive pattern that doesn't give enough simple patterns to match + all the arguments in the constructor. If set (the default), |Coq| generates + additional names to match the number of arguments. + Unsetting the option will put the additional hypotheses in the goal instead, behavior that is more + similar to |SSR|'s intro patterns. + + .. deprecated:: 8.10 + +.. _intropattern_cons_note: + +.. note:: + + :n:`A \/ B` and :n:`A /\ B` use infix notation to refer to the inductive + types :n:`or` and :n:`and`. + :n:`or` has multiple constructors (:n:`or_introl` and :n:`or_intror`), + while :n:`and` has a single constructor (:n:`conj`) with multiple parameters + (:n:`A` and :n:`B`). + These are defined in theories/Init/Logic.v. The "where" clauses define the + infix notation for "or" and "and". + + .. coqdoc:: + + Inductive or (A B:Prop) : Prop := + | or_introl : A -> A \/ B + | or_intror : B -> A \/ B + where "A \/ B" := (or A B) : type_scope. + + Inductive and (A B:Prop) : Prop := + conj : A -> B -> A /\ B + where "A /\ B" := (and A B) : type_scope. + +.. note:: + + :n:`intros {+ p}` is not always equivalent to :n:`intros p; ... ; intros p` + if some of the :n:`p` are :g:`_`. In the first form, all erasures are done + at once, while they're done sequentially for each tactic in the second form. + If the second matched term depends on the first matched term and the pattern + for both is :g:`_` (i.e., both will be erased), the first :n:`intros` in the second + form will fail because the second matched term still has the dependency on the first. + +Examples: + +.. _intropattern_conj_ex: + + .. example:: intro pattern for /\\ + + .. coqtop:: reset none + + Goal forall (A: Prop) (B: Prop), (A /\ B) -> True. + + .. coqtop:: out + + intros. + + .. coqtop:: all + + destruct H as (HA & HB). + +.. _intropattern_disj_ex: + + .. example:: intro pattern for \\/ + + .. coqtop:: reset none + + Goal forall (A: Prop) (B: Prop), (A \/ B) -> True. + + .. coqtop:: out + + intros. + + .. coqtop:: all + + destruct H as [HA|HB]. all: swap 1 2. + +.. _intropattern_rarrow_ex: + + .. example:: -> intro pattern + + .. coqtop:: reset none + + Goal forall (x:nat) (y:nat) (z:nat), (x = y) -> (y = z) -> (x = z). + + .. coqtop:: out + + intros * H. + + .. coqtop:: all + + intros ->. + +.. _intropattern_inj_discr_ex: + + .. example:: [=] intro pattern + + The first :n:`intros [=]` uses :tacn:`injection` to strip :n:`(S ...)` from + both sides of the matched equality. The second uses :tacn:`discriminate` on + the contradiction :n:`1 = 2` (internally represented as :n:`(S O) = (S (S O))`) + to complete the goal. + + .. coqtop:: reset none + + Goal forall (n m:nat), (S n) = (S m) -> (S O)=(S (S O)) -> False. + + .. coqtop:: out + + intros *. + + .. coqtop:: all + + intros [= H]. + + .. coqtop:: all + + intros [=]. + +.. _intropattern_ampersand_ex: + + .. example:: (A & B & ...) intro pattern + + .. coqtop:: reset none + + Parameters (A : Prop) (B: nat -> Prop) (C: Prop). + + .. coqtop:: out + + Goal A /\ (exists x:nat, B x /\ C) -> True. + + .. coqtop:: all + + intros (a & x & b & c). + +.. _intropattern_star_ex: + + .. example:: * intro pattern + + .. coqtop:: reset out + + Goal forall (A: Prop) (B: Prop), A -> B. + + .. coqtop:: all + + intros *. + +.. _intropattern_2stars_ex: + + .. example:: ** pattern ("intros \**" is equivalent to "intros") + + .. coqtop:: reset out + + Goal forall (A: Prop) (B: Prop), A -> B. + + .. coqtop:: all + + intros **. + + .. example:: compound intro pattern + + .. coqtop:: reset out + + Goal forall A B C:Prop, A \/ B /\ C -> (A -> C) -> C. + + .. coqtop:: all + + intros * [a | (_,c)] f. + all: swap 1 2. + +.. _intropattern_injection_ex: + + .. example:: combined intro pattern using [=] -> and % + + .. coqtop:: reset none + + Require Import Coq.Lists.List. + Section IntroPatterns. + Variables (A : Type) (xs ys : list A). + + .. coqtop:: out + + Example ThreeIntroPatternsCombined : + S (length ys) = 1 -> xs ++ ys = xs. + + .. coqtop:: all + + intros [=->%length_zero_iff_nil]. + + * `intros` would add :g:`H : S (length ys) = 1` + * `intros [=]` would additionally apply :tacn:`injection` to :g:`H` to yield :g:`H0 : length ys = 0` + * `intros [=->%length_zero_iff_nil]` applies the theorem, making H the equality :g:`l=nil`, + which is then applied as for :g:`->`. + + .. coqdoc:: + + Theorem length_zero_iff_nil (l : list A): + length l = 0 <-> l=nil. + + The example is based on `Tej Chajed's coq-tricks <https://github.com/tchajed/coq-tricks/blob/8e6efe4971ed828ac8bdb5512c1f615d7d62691e/src/IntroPatterns.v>`_ + +.. _occurrencessets: + +Occurrence sets and occurrence clauses +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +An occurrence clause is a modifier to some tactics that obeys the +following syntax: + + .. productionlist:: sentence + occurrence_clause : in `goal_occurrences` + goal_occurrences : [`ident` [`at_occurrences`], ... , `ident` [`at_occurrences`] [|- [* [`at_occurrences`]]]] + : * |- [* [`at_occurrences`]] + : * + at_occurrences : at `occurrences` + occurrences : [-] `num` ... `num` + +The role of an occurrence clause is to select a set of occurrences of a term +in a goal. In the first case, the :n:`@ident {? at {* num}}` parts indicate +that occurrences have to be selected in the hypotheses named :token:`ident`. +If no numbers are given for hypothesis :token:`ident`, then all the +occurrences of :token:`term` in the hypothesis are selected. If numbers are +given, they refer to occurrences of :token:`term` when the term is printed +using option :flag:`Printing All`, counting from left to right. In particular, +occurrences of :token:`term` in implicit arguments +(see :ref:`ImplicitArguments`) or coercions (see :ref:`Coercions`) are +counted. + +If a minus sign is given between ``at`` and the list of occurrences, it +negates the condition so that the clause denotes all the occurrences +except the ones explicitly mentioned after the minus sign. + +As an exception to the left-to-right order, the occurrences in +the return subexpression of a match are considered *before* the +occurrences in the matched term. + +In the second case, the ``*`` on the left of ``|-`` means that all occurrences +of term are selected in every hypothesis. + +In the first and second case, if ``*`` is mentioned on the right of ``|-``, the +occurrences of the conclusion of the goal have to be selected. If some numbers +are given, then only the occurrences denoted by these numbers are selected. If +no numbers are given, all occurrences of :token:`term` in the goal are selected. + +Finally, the last notation is an abbreviation for ``* |- *``. Note also +that ``|-`` is optional in the first case when no ``*`` is given. + +Here are some tactics that understand occurrence clauses: :tacn:`set`, +:tacn:`remember`, :tacn:`induction`, :tacn:`destruct`. + + +.. seealso:: + + :ref:`Managingthelocalcontext`, :ref:`caseanalysisandinduction`, + :ref:`printing_constructions_full`. + + +.. _applyingtheorems: + +Applying theorems +--------------------- + +.. tacn:: exact @term + :name: exact + + This tactic applies to any goal. It gives directly the exact proof + term of the goal. Let ``T`` be our goal, let ``p`` be a term of type ``U`` then + ``exact p`` succeeds iff ``T`` and ``U`` are convertible (see + :ref:`Conversion-rules`). + + .. exn:: Not an exact proof. + :undocumented: + + .. tacv:: eexact @term. + :name: eexact + + This tactic behaves like :tacn:`exact` but is able to handle terms and + goals with existential variables. + +.. tacn:: assumption + :name: assumption + + This tactic looks in the local context for a hypothesis whose type is + convertible to the goal. If it is the case, the subgoal is proved. + Otherwise, it fails. + + .. exn:: No such assumption. + :undocumented: + + .. tacv:: eassumption + :name: eassumption + + This tactic behaves like :tacn:`assumption` but is able to handle + goals with existential variables. + +.. tacn:: refine @term + :name: refine + + This tactic applies to any goal. It behaves like :tacn:`exact` with a big + difference: the user can leave some holes (denoted by ``_`` + or :n:`(_ : @type)`) in the term. :tacn:`refine` will generate as many + subgoals as there are holes in the term. The type of holes must be either + synthesized by the system or declared by an explicit cast + like ``(_ : nat -> Prop)``. Any subgoal that + occurs in other subgoals is automatically shelved, as if calling + :tacn:`shelve_unifiable`. This low-level tactic can be + useful to advanced users. + + .. example:: + + .. coqtop:: reset all + + Inductive Option : Set := + | Fail : Option + | Ok : bool -> Option. + + Definition get : forall x:Option, x <> Fail -> bool. + refine + (fun x:Option => + match x return x <> Fail -> bool with + | Fail => _ + | Ok b => fun _ => b + end). + intros; absurd (Fail = Fail); trivial. + Defined. + + .. exn:: Invalid argument. + + The tactic :tacn:`refine` does not know what to do with the term you gave. + + .. exn:: Refine passed ill-formed term. + + The term you gave is not a valid proof (not easy to debug in general). This + message may also occur in higher-level tactics that call :tacn:`refine` + internally. + + .. exn:: Cannot infer a term for this placeholder. + :name: Cannot infer a term for this placeholder. (refine) + + There is a hole in the term you gave whose type cannot be inferred. Put a + cast around it. + + .. tacv:: simple refine @term + :name: simple refine + + This tactic behaves like refine, but it does not shelve any subgoal. It does + not perform any beta-reduction either. + + .. tacv:: notypeclasses refine @term + :name: notypeclasses refine + + This tactic behaves like :tacn:`refine` except it performs type checking without + resolution of typeclasses. + + .. tacv:: simple notypeclasses refine @term + :name: simple notypeclasses refine + + This tactic behaves like :tacn:`simple refine` except it performs type checking + without resolution of typeclasses. + + .. flag:: Debug Unification + + Enables printing traces of unification steps used during + elaboration/typechecking and the :tacn:`refine` tactic. + +.. tacn:: apply @term + :name: apply + + This tactic applies to any goal. The argument term is a term well-formed in + the local context. The tactic :tacn:`apply` tries to match the current goal + against the conclusion of the type of :token:`term`. If it succeeds, then + the tactic returns as many subgoals as the number of non-dependent premises + of the type of term. If the conclusion of the type of :token:`term` does + not match the goal *and* the conclusion is an inductive type isomorphic to + a tuple type, then each component of the tuple is recursively matched to + the goal in the left-to-right order. + + The tactic :tacn:`apply` relies on first-order unification with dependent + types unless the conclusion of the type of :token:`term` is of the form + :n:`P (t__1 ... t__n)` with ``P`` to be instantiated. In the latter case, + the behavior depends on the form of the goal. If the goal is of the form + :n:`(fun x => Q) u__1 ... u__n` and the :n:`t__i` and :n:`u__i` unify, + then :g:`P` is taken to be :g:`(fun x => Q)`. Otherwise, :tacn:`apply` + tries to define :g:`P` by abstracting over :g:`t_1 ... t__n` in the goal. + See :tacn:`pattern` to transform the goal so that it + gets the form :n:`(fun x => Q) u__1 ... u__n`. + + .. exn:: Unable to unify @term with @term. + + The :tacn:`apply` tactic failed to match the conclusion of :token:`term` + and the current goal. You can help the :tacn:`apply` tactic by + transforming your goal with the :tacn:`change` or :tacn:`pattern` + tactics. + + .. exn:: Unable to find an instance for the variables {+ @ident}. + + This occurs when some instantiations of the premises of :token:`term` are not deducible + from the unification. This is the case, for instance, when you want to apply a + transitivity property. In this case, you have to use one of the variants below: + + .. tacv:: apply @term with {+ @term} + + Provides apply with explicit instantiations for all dependent premises of the + type of term that do not occur in the conclusion and consequently cannot be + found by unification. Notice that the collection :n:`{+ @term}` must be given + according to the order of these dependent premises of the type of term. + + .. exn:: Not the right number of missing arguments. + :undocumented: + + .. tacv:: apply @term with @bindings_list + + This also provides apply with values for instantiating premises. Here, variables + are referred by names and non-dependent products by increasing numbers (see + :ref:`bindings list <bindingslist>`). + + .. tacv:: apply {+, @term} + + This is a shortcut for :n:`apply @term__1; [.. | ... ; [ .. | apply @term__n] ... ]`, + i.e. for the successive applications of :n:`@term`:sub:`i+1` on the last subgoal + generated by :n:`apply @term__i` , starting from the application of :n:`@term__1`. + + .. tacv:: eapply @term + :name: eapply + + The tactic :tacn:`eapply` behaves like :tacn:`apply` but it does not fail when no + instantiations are deducible for some variables in the premises. Rather, it + turns these variables into existential variables which are variables still to + instantiate (see :ref:`Existential-Variables`). The instantiation is + intended to be found later in the proof. + + .. tacv:: simple apply @term. + + This behaves like :tacn:`apply` but it reasons modulo conversion only on subterms + that contain no variables to instantiate. For instance, the following example + does not succeed because it would require the conversion of ``id ?foo`` and + :g:`O`. + + .. example:: + + .. coqtop:: all + + Definition id (x : nat) := x. + Parameter H : forall y, id y = y. + Goal O = O. + Fail simple apply H. + + Because it reasons modulo a limited amount of conversion, :tacn:`simple apply` fails + quicker than :tacn:`apply` and it is then well-suited for uses in user-defined + tactics that backtrack often. Moreover, it does not traverse tuples as :tacn:`apply` + does. + + .. tacv:: {? simple} apply {+, @term {? with @bindings_list}} + {? simple} eapply {+, @term {? with @bindings_list}} + :name: simple apply; simple eapply + + This summarizes the different syntaxes for :tacn:`apply` and :tacn:`eapply`. + + .. tacv:: lapply @term + :name: lapply + + This tactic applies to any goal, say :g:`G`. The argument term has to be + well-formed in the current context, its type being reducible to a non-dependent + product :g:`A -> B` with :g:`B` possibly containing products. Then it generates + two subgoals :g:`B->G` and :g:`A`. Applying ``lapply H`` (where :g:`H` has type + :g:`A->B` and :g:`B` does not start with a product) does the same as giving the + sequence ``cut B. 2:apply H.`` where ``cut`` is described below. + + .. warn:: When @term contains more than one non dependent product the tactic lapply only takes into account the first product. + :undocumented: + +.. example:: + + Assume we have a transitive relation ``R`` on ``nat``: + + .. coqtop:: reset in + + Parameter R : nat -> nat -> Prop. + + Axiom Rtrans : forall x y z:nat, R x y -> R y z -> R x z. + + Parameters n m p : nat. + + Axiom Rnm : R n m. + + Axiom Rmp : R m p. + + Consider the goal ``(R n p)`` provable using the transitivity of ``R``: + + .. coqtop:: in + + Goal R n p. + + The direct application of ``Rtrans`` with ``apply`` fails because no value + for ``y`` in ``Rtrans`` is found by ``apply``: + + .. coqtop:: all fail + + apply Rtrans. + + A solution is to ``apply (Rtrans n m p)`` or ``(Rtrans n m)``. + + .. coqtop:: all + + apply (Rtrans n m p). + + Note that ``n`` can be inferred from the goal, so the following would work + too. + + .. coqtop:: in restart + + apply (Rtrans _ m). + + More elegantly, ``apply Rtrans with (y:=m)`` allows only mentioning the + unknown m: + + .. coqtop:: in restart + + apply Rtrans with (y := m). + + Another solution is to mention the proof of ``(R x y)`` in ``Rtrans`` + + .. coqtop:: all restart + + apply Rtrans with (1 := Rnm). + + ... or the proof of ``(R y z)``. + + .. coqtop:: all restart + + apply Rtrans with (2 := Rmp). + + On the opposite, one can use ``eapply`` which postpones the problem of + finding ``m``. Then one can apply the hypotheses ``Rnm`` and ``Rmp``. This + instantiates the existential variable and completes the proof. + + .. coqtop:: all restart abort + + eapply Rtrans. + + apply Rnm. + + apply Rmp. + +.. note:: + When the conclusion of the type of the term to ``apply`` is an inductive + type isomorphic to a tuple type and ``apply`` looks recursively whether a + component of the tuple matches the goal, it excludes components whose + statement would result in applying an universal lemma of the form + ``forall A, ... -> A``. Excluding this kind of lemma can be avoided by + setting the following option: + +.. flag:: Universal Lemma Under Conjunction + + This option, which preserves compatibility with versions of Coq prior to + 8.4 is also available for :n:`apply @term in @ident` (see :tacn:`apply ... in`). + +.. tacn:: apply @term in @ident + :name: apply ... in + + This tactic applies to any goal. The argument :token:`term` is a term + well-formed in the local context and the argument :token:`ident` is an + hypothesis of the context. + The tactic :n:`apply @term in @ident` tries to match the conclusion of the + type of :token:`ident` against a non-dependent premise of the type + of :token:`term`, trying them from right to left. If it succeeds, the + statement of hypothesis :token:`ident` is replaced by the conclusion of + the type of :token:`term`. The tactic also returns as many subgoals as the + number of other non-dependent premises in the type of :token:`term` and of + the non-dependent premises of the type of :token:`ident`. If the conclusion + of the type of :token:`term` does not match the goal *and* the conclusion + is an inductive type isomorphic to a tuple type, then + the tuple is (recursively) decomposed and the first component of the tuple + of which a non-dependent premise matches the conclusion of the type of + :token:`ident`. Tuples are decomposed in a width-first left-to-right order + (for instance if the type of :g:`H1` is :g:`A <-> B` and the type of + :g:`H2` is :g:`A` then :g:`apply H1 in H2` transforms the type of :g:`H2` + into :g:`B`). The tactic :tacn:`apply` relies on first-order pattern matching + with dependent types. + + .. exn:: Statement without assumptions. + + This happens if the type of :token:`term` has no non-dependent premise. + + .. exn:: Unable to apply. + + This happens if the conclusion of :token:`ident` does not match any of + the non-dependent premises of the type of :token:`term`. + + .. tacv:: apply {+, @term} in @ident + + This applies each :token:`term` in sequence in :token:`ident`. + + .. tacv:: apply {+, @term with @bindings_list} in @ident + + This does the same but uses the bindings in each :n:`(@ident := @term)` to + instantiate the parameters of the corresponding type of :token:`term` + (see :ref:`bindings list <bindingslist>`). + + .. tacv:: eapply {+, @term {? with @bindings_list } } in @ident + + This works as :tacn:`apply ... in` but turns unresolved bindings into + existential variables, if any, instead of failing. + + .. tacv:: apply {+, @term {? with @bindings_list } } in @ident as @simple_intropattern + :name: apply ... in ... as + + This works as :tacn:`apply ... in` then applies the :token:`simple_intropattern` + to the hypothesis :token:`ident`. + + .. tacv:: simple apply @term in @ident + + This behaves like :tacn:`apply ... in` but it reasons modulo conversion + only on subterms that contain no variables to instantiate. For instance, + if :g:`id := fun x:nat => x` and :g:`H: forall y, id y = y -> True` and + :g:`H0 : O = O` then :g:`simple apply H in H0` does not succeed because it + would require the conversion of :g:`id ?x` and :g:`O` where :g:`?x` is + an existential variable to instantiate. + Tactic :n:`simple apply @term in @ident` does not + either traverse tuples as :n:`apply @term in @ident` does. + + .. tacv:: {? simple} apply {+, @term {? with @bindings_list}} in @ident {? as @simple_intropattern} + {? simple} eapply {+, @term {? with @bindings_list}} in @ident {? as @simple_intropattern} + + This summarizes the different syntactic variants of :n:`apply @term in @ident` + and :n:`eapply @term in @ident`. + +.. tacn:: constructor @num + :name: constructor + + This tactic applies to a goal such that its conclusion is an inductive + type (say :g:`I`). The argument :token:`num` must be less or equal to the + numbers of constructor(s) of :g:`I`. Let :n:`c__i` be the i-th + constructor of :g:`I`, then :g:`constructor i` is equivalent to + :n:`intros; apply c__i`. + + .. exn:: Not an inductive product. + :undocumented: + + .. exn:: Not enough constructors. + :undocumented: + + .. tacv:: constructor + + This tries :g:`constructor 1` then :g:`constructor 2`, ..., then + :g:`constructor n` where ``n`` is the number of constructors of the head + of the goal. + + .. tacv:: constructor @num with @bindings_list + + Let ``c`` be the i-th constructor of :g:`I`, then + :n:`constructor i with @bindings_list` is equivalent to + :n:`intros; apply c with @bindings_list`. + + .. warning:: + + The terms in the :token:`bindings_list` are checked in the context + where constructor is executed and not in the context where :tacn:`apply` + is executed (the introductions are not taken into account). + + .. tacv:: split {? with @bindings_list } + :name: split + + This applies only if :g:`I` has a single constructor. It is then + equivalent to :n:`constructor 1 {? with @bindings_list }`. It is + typically used in the case of a conjunction :math:`A \wedge B`. + + .. tacv:: exists @bindings_list + :name: exists + + This applies only if :g:`I` has a single constructor. It is then equivalent + to :n:`intros; constructor 1 with @bindings_list.` It is typically used in + the case of an existential quantification :math:`\exists x, P(x).` + + .. tacv:: exists {+, @bindings_list } + + This iteratively applies :n:`exists @bindings_list`. + + .. exn:: Not an inductive goal with 1 constructor. + :undocumented: + + .. tacv:: left {? with @bindings_list } + right {? with @bindings_list } + :name: left; right + + These tactics apply only if :g:`I` has two constructors, for + instance in the case of a disjunction :math:`A \vee B`. + Then, they are respectively equivalent to + :n:`constructor 1 {? with @bindings_list }` and + :n:`constructor 2 {? with @bindings_list }`. + + .. exn:: Not an inductive goal with 2 constructors. + :undocumented: + + .. tacv:: econstructor + eexists + esplit + eleft + eright + :name: econstructor; eexists; esplit; eleft; eright + + These tactics and their variants behave like :tacn:`constructor`, + :tacn:`exists`, :tacn:`split`, :tacn:`left`, :tacn:`right` and their + variants but they introduce existential variables instead of failing + when the instantiation of a variable cannot be found + (cf. :tacn:`eapply` and :tacn:`apply`). + +.. flag:: Debug Tactic Unification + + Enables printing traces of unification steps in tactic unification. + Tactic unification is used in tactics such as :tacn:`apply` and :tacn:`rewrite`. + +.. _managingthelocalcontext: + +Managing the local context +------------------------------ + +.. tacn:: intro + :name: intro + + This tactic applies to a goal that is either a product or starts with a + let-binder. If the goal is a product, the tactic implements the "Lam" rule + given in :ref:`Typing-rules` [1]_. If the goal starts with a let-binder, + then the tactic implements a mix of the "Let" and "Conv". + + If the current goal is a dependent product :g:`forall x:T, U` + (resp :g:`let x:=t in U`) then :tacn:`intro` puts :g:`x:T` (resp :g:`x:=t`) + in the local context. The new subgoal is :g:`U`. + + If the goal is a non-dependent product :math:`T \rightarrow U`, then it + puts in the local context either :g:`Hn:T` (if :g:`T` is of type :g:`Set` + or :g:`Prop`) or :g:`Xn:T` (if the type of :g:`T` is :g:`Type`). + The optional index ``n`` is such that ``Hn`` or ``Xn`` is a fresh + identifier. In both cases, the new subgoal is :g:`U`. + + If the goal is an existential variable, :tacn:`intro` forces the resolution + of the existential variable into a dependent product :math:`\forall`\ :g:`x:?X, ?Y`, + puts :g:`x:?X` in the local context and leaves :g:`?Y` as a new subgoal + allowed to depend on :g:`x`. + + The tactic :tacn:`intro` applies the tactic :tacn:`hnf` + until :tacn:`intro` can be applied or the goal is not head-reducible. + + .. exn:: No product even after head-reduction. + :undocumented: + + .. tacv:: intro @ident + + This applies :tacn:`intro` but forces :token:`ident` to be the name of + the introduced hypothesis. + + .. exn:: @ident is already used. + :undocumented: + + .. note:: + + If a name used by intro hides the base name of a global constant then + the latter can still be referred to by a qualified name + (see :ref:`Qualified-names`). + + .. tacv:: intros + :name: intros + + This repeats :tacn:`intro` until it meets the head-constant. It never + reduces head-constants and it never fails. + + .. tacv:: intros {+ @ident}. + + This is equivalent to the composed tactic :n:`intro @ident; ... ; intro @ident`. + + .. tacv:: intros until @ident + + This repeats intro until it meets a premise of the goal having the + form :n:`(@ident : @type)` and discharges the variable + named :token:`ident` of the current goal. + + .. exn:: No such hypothesis in current goal. + :undocumented: + + .. tacv:: intros until @num + + This repeats :tacn:`intro` until the :token:`num`\-th non-dependent + product. + + .. example:: + + On the subgoal :g:`forall x y : nat, x = y -> y = x` the + tactic :n:`intros until 1` is equivalent to :n:`intros x y H`, + as :g:`x = y -> y = x` is the first non-dependent product. + + On the subgoal :g:`forall x y z : nat, x = y -> y = x` the + tactic :n:`intros until 1` is equivalent to :n:`intros x y z` + as the product on :g:`z` can be rewritten as a non-dependent + product: :g:`forall x y : nat, nat -> x = y -> y = x`. + + .. exn:: No such hypothesis in current goal. + + This happens when :token:`num` is 0 or is greater than the number of + non-dependent products of the goal. + + .. tacv:: intro {? @ident__1 } after @ident__2 + intro {? @ident__1 } before @ident__2 + intro {? @ident__1 } at top + intro {? @ident__1 } at bottom + + These tactics apply :n:`intro {? @ident__1}` and move the freshly + introduced hypothesis respectively after the hypothesis :n:`@ident__2`, + before the hypothesis :n:`@ident__2`, at the top of the local context, + or at the bottom of the local context. All hypotheses on which the new + hypothesis depends are moved too so as to respect the order of + dependencies between hypotheses. It is equivalent to :n:`intro {? @ident__1 }` + followed by the appropriate call to :tacn:`move ... after ...`, + :tacn:`move ... before ...`, :tacn:`move ... at top`, + or :tacn:`move ... at bottom`. + + .. note:: + + :n:`intro at bottom` is a synonym for :n:`intro` with no argument. + + .. exn:: No such hypothesis: @ident. + :undocumented: + +.. tacn:: intros @intropattern_list + :name: intros ... + + Introduces one or more variables or hypotheses from the goal by matching the + intro patterns. See the description in :ref:`intropatterns`. + +.. tacn:: eintros @intropattern_list + :name: eintros + + Works just like :tacn:`intros ...` except that it creates existential variables + for any unresolved variables rather than failing. + +.. tacn:: clear @ident + :name: clear + + This tactic erases the hypothesis named :n:`@ident` in the local context of + the current goal. As a consequence, :n:`@ident` is no more displayed and no + more usable in the proof development. + + .. exn:: No such hypothesis. + :undocumented: + + .. exn:: @ident is used in the conclusion. + :undocumented: + + .. exn:: @ident is used in the hypothesis @ident. + :undocumented: + + .. tacv:: clear {+ @ident} + + This is equivalent to :n:`clear @ident. ... clear @ident.` + + .. tacv:: clear - {+ @ident} + + This variant clears all the hypotheses except the ones depending in the + hypotheses named :n:`{+ @ident}` and in the goal. + + .. tacv:: clear + + This variants clears all the hypotheses except the ones the goal depends on. + + .. tacv:: clear dependent @ident + + This clears the hypothesis :token:`ident` and all the hypotheses that + depend on it. + + .. tacv:: clearbody {+ @ident} + :name: clearbody + + This tactic expects :n:`{+ @ident}` to be local definitions and clears + their respective bodies. + In other words, it turns the given definitions into assumptions. + + .. exn:: @ident is not a local definition. + :undocumented: + +.. tacn:: revert {+ @ident} + :name: revert + + This applies to any goal with variables :n:`{+ @ident}`. It moves the hypotheses + (possibly defined) to the goal, if this respects dependencies. This tactic is + the inverse of :tacn:`intro`. + + .. exn:: No such hypothesis. + :undocumented: + + .. exn:: @ident__1 is used in the hypothesis @ident__2. + :undocumented: + + .. tacv:: revert dependent @ident + :name: revert dependent + + This moves to the goal the hypothesis :token:`ident` and all the + hypotheses that depend on it. + +.. tacn:: move @ident__1 after @ident__2 + :name: move ... after ... + + This moves the hypothesis named :n:`@ident__1` in the local context after + the hypothesis named :n:`@ident__2`, where “after” is in reference to the + direction of the move. The proof term is not changed. + + If :n:`@ident__1` comes before :n:`@ident__2` in the order of dependencies, + then all the hypotheses between :n:`@ident__1` and :n:`@ident__2` that + (possibly indirectly) depend on :n:`@ident__1` are moved too, and all of + them are thus moved after :n:`@ident__2` in the order of dependencies. + + If :n:`@ident__1` comes after :n:`@ident__2` in the order of dependencies, + then all the hypotheses between :n:`@ident__1` and :n:`@ident__2` that + (possibly indirectly) occur in the type of :n:`@ident__1` are moved too, + and all of them are thus moved before :n:`@ident__2` in the order of + dependencies. + + .. tacv:: move @ident__1 before @ident__2 + :name: move ... before ... + + This moves :n:`@ident__1` towards and just before the hypothesis + named :n:`@ident__2`. As for :tacn:`move ... after ...`, dependencies + over :n:`@ident__1` (when :n:`@ident__1` comes before :n:`@ident__2` in + the order of dependencies) or in the type of :n:`@ident__1` + (when :n:`@ident__1` comes after :n:`@ident__2` in the order of + dependencies) are moved too. + + .. tacv:: move @ident at top + :name: move ... at top + + This moves :token:`ident` at the top of the local context (at the beginning + of the context). + + .. tacv:: move @ident at bottom + :name: move ... at bottom + + This moves :token:`ident` at the bottom of the local context (at the end of + the context). + + .. exn:: No such hypothesis. + :undocumented: + + .. exn:: Cannot move @ident__1 after @ident__2: it occurs in the type of @ident__2. + :undocumented: + + .. exn:: Cannot move @ident__1 after @ident__2: it depends on @ident__2. + :undocumented: + + .. example:: + + .. coqtop:: reset all + + Goal forall x :nat, x = 0 -> forall z y:nat, y=y-> 0=x. + intros x H z y H0. + move x after H0. + Undo. + move x before H0. + Undo. + move H0 after H. + Undo. + move H0 before H. + +.. tacn:: rename @ident__1 into @ident__2 + :name: rename + + This renames hypothesis :n:`@ident__1` into :n:`@ident__2` in the current + context. The name of the hypothesis in the proof-term, however, is left + unchanged. + + .. tacv:: rename {+, @ident__i into @ident__j} + + This renames the variables :n:`@ident__i` into :n:`@ident__j` in parallel. + In particular, the target identifiers may contain identifiers that exist in + the source context, as long as the latter are also renamed by the same + tactic. + + .. exn:: No such hypothesis. + :undocumented: + + .. exn:: @ident is already used. + :undocumented: + +.. tacn:: set (@ident := @term) + :name: set + + This replaces :token:`term` by :token:`ident` in the conclusion of the + current goal and adds the new definition :n:`@ident := @term` to the + local context. + + If :token:`term` has holes (i.e. subexpressions of the form “`_`”), the + tactic first checks that all subterms matching the pattern are compatible + before doing the replacement using the leftmost subterm matching the + pattern. + + .. exn:: The variable @ident is already defined. + :undocumented: + + .. tacv:: set (@ident := @term) in @goal_occurrences + + This notation allows specifying which occurrences of :token:`term` have + to be substituted in the context. The :n:`in @goal_occurrences` clause + is an occurrence clause whose syntax and behavior are described in + :ref:`goal occurrences <occurrencessets>`. + + .. tacv:: set (@ident @binders := @term) {? in @goal_occurrences } + + This is equivalent to :n:`set (@ident := fun @binders => @term) {? in @goal_occurrences }`. + + .. tacv:: set @term {? in @goal_occurrences } + + This behaves as :n:`set (@ident := @term) {? in @goal_occurrences }` + but :token:`ident` is generated by Coq. + + .. tacv:: eset (@ident {? @binders } := @term) {? in @goal_occurrences } + eset @term {? in @goal_occurrences } + :name: eset; _ + + While the different variants of :tacn:`set` expect that no existential + variables are generated by the tactic, :tacn:`eset` removes this + constraint. In practice, this is relevant only when :tacn:`eset` is + used as a synonym of :tacn:`epose`, i.e. when the :token:`term` does + not occur in the goal. + +.. tacn:: remember @term as @ident__1 {? eqn:@naming_intropattern } + :name: remember + + This behaves as :n:`set (@ident := @term) in *`, using a logical + (Leibniz’s) equality instead of a local definition. + Use :n:`@naming_intropattern` to name or split up the new equation. + + .. tacv:: remember @term as @ident__1 {? eqn:@naming_intropattern } in @goal_occurrences + + This is a more general form of :tacn:`remember` that remembers the + occurrences of :token:`term` specified by an occurrence set. + + .. tacv:: eremember @term as @ident__1 {? eqn:@naming_intropattern } {? in @goal_occurrences } + :name: eremember + + While the different variants of :tacn:`remember` expect that no + existential variables are generated by the tactic, :tacn:`eremember` + removes this constraint. + +.. tacn:: pose (@ident := @term) + :name: pose + + This adds the local definition :n:`@ident := @term` to the current context + without performing any replacement in the goal or in the hypotheses. It is + equivalent to :n:`set (@ident := @term) in |-`. + + .. tacv:: pose (@ident @binders := @term) + + This is equivalent to :n:`pose (@ident := fun @binders => @term)`. + + .. tacv:: pose @term + + This behaves as :n:`pose (@ident := @term)` but :token:`ident` is + generated by Coq. + + .. tacv:: epose (@ident {? @binders} := @term) + epose @term + :name: epose; _ + + While the different variants of :tacn:`pose` expect that no + existential variables are generated by the tactic, :tacn:`epose` + removes this constraint. + +.. tacn:: decompose [{+ @qualid}] @term + :name: decompose + + This tactic recursively decomposes a complex proposition in order to + obtain atomic ones. + + .. example:: + + .. coqtop:: reset all + + Goal forall A B C:Prop, A /\ B /\ C \/ B /\ C \/ C /\ A -> C. + intros A B C H; decompose [and or] H. + all: assumption. + Qed. + + .. note:: + + :tacn:`decompose` does not work on right-hand sides of implications or + products. + + .. tacv:: decompose sum @term + + This decomposes sum types (like :g:`or`). + + .. tacv:: decompose record @term + + This decomposes record types (inductive types with one constructor, + like :g:`and` and :g:`exists` and those defined with the :cmd:`Record` + command. + + +.. _controllingtheproofflow: + +Controlling the proof flow +------------------------------ + +.. tacn:: assert (@ident : @type) + :name: assert + + This tactic applies to any goal. :n:`assert (H : U)` adds a new hypothesis + of name :n:`H` asserting :g:`U` to the current goal and opens a new subgoal + :g:`U` [2]_. The subgoal :g:`U` comes first in the list of subgoals remaining to + prove. + + .. exn:: Not a proposition or a type. + + Arises when the argument :token:`type` is neither of type :g:`Prop`, + :g:`Set` nor :g:`Type`. + + .. tacv:: assert @type + + This behaves as :n:`assert (@ident : @type)` but :n:`@ident` is + generated by Coq. + + .. tacv:: assert @type by @tactic + + This tactic behaves like :tacn:`assert` but applies tactic to solve the + subgoals generated by assert. + + .. exn:: Proof is not complete. + :name: Proof is not complete. (assert) + :undocumented: + + .. tacv:: assert @type as @simple_intropattern + + If :n:`simple_intropattern` is an intro pattern (see :ref:`intropatterns`), + the hypothesis is named after this introduction pattern (in particular, if + :n:`simple_intropattern` is :n:`@ident`, the tactic behaves like + :n:`assert (@ident : @type)`). If :n:`simple_intropattern` is an action + introduction pattern, the tactic behaves like :n:`assert @type` followed by + the action done by this introduction pattern. + + .. tacv:: assert @type as @simple_intropattern by @tactic + + This combines the two previous variants of :tacn:`assert`. + + .. tacv:: assert (@ident := @term) + + This behaves as :n:`assert (@ident : @type) by exact @term` where + :token:`type` is the type of :token:`term`. This is equivalent to using + :tacn:`pose proof`. If the head of term is :token:`ident`, the tactic + behaves as :tacn:`specialize`. + + .. exn:: Variable @ident is already declared. + :undocumented: + +.. tacv:: eassert @type as @simple_intropattern by @tactic + :name: eassert + + While the different variants of :tacn:`assert` expect that no existential + variables are generated by the tactic, :tacn:`eassert` removes this constraint. + This allows not to specify the asserted statement completeley before starting + to prove it. + +.. tacv:: pose proof @term {? as @simple_intropattern} + :name: pose proof + + This tactic behaves like :n:`assert @type {? as @simple_intropattern} by exact @term` + where :token:`type` is the type of :token:`term`. In particular, + :n:`pose proof @term as @ident` behaves as :n:`assert (@ident := @term)` + and :n:`pose proof @term as @simple_intropattern` is the same as applying the + :token:`simple_intropattern` to :token:`term`. + +.. tacv:: epose proof @term {? as @simple_intropattern} + :name: epose proof + + While :tacn:`pose proof` expects that no existential variables are generated by + the tactic, :tacn:`epose proof` removes this constraint. + +.. tacv:: enough (@ident : @type) + :name: enough + + This adds a new hypothesis of name :token:`ident` asserting :token:`type` to the + goal the tactic :tacn:`enough` is applied to. A new subgoal stating :token:`type` is + inserted after the initial goal rather than before it as :tacn:`assert` would do. + +.. tacv:: enough @type + + This behaves like :n:`enough (@ident : @type)` with the name :token:`ident` of + the hypothesis generated by Coq. + +.. tacv:: enough @type as @simple_intropattern + + This behaves like :n:`enough @type` using :token:`simple_intropattern` to name or + destruct the new hypothesis. + +.. tacv:: enough (@ident : @type) by @tactic + enough @type {? as @simple_intropattern } by @tactic + + This behaves as above but with :token:`tactic` expected to solve the initial goal + after the extra assumption :token:`type` is added and possibly destructed. If the + :n:`as @simple_intropattern` clause generates more than one subgoal, :token:`tactic` is + applied to all of them. + +.. tacv:: eenough @type {? as @simple_intropattern } {? by @tactic } + eenough (@ident : @type) {? by @tactic } + :name: eenough; _ + + While the different variants of :tacn:`enough` expect that no existential + variables are generated by the tactic, :tacn:`eenough` removes this constraint. + +.. tacv:: cut @type + :name: cut + + This tactic applies to any goal. It implements the non-dependent case of + the “App” rule given in :ref:`typing-rules`. (This is Modus Ponens inference + rule.) :n:`cut U` transforms the current goal :g:`T` into the two following + subgoals: :g:`U -> T` and :g:`U`. The subgoal :g:`U -> T` comes first in the + list of remaining subgoal to prove. + +.. tacv:: specialize (@ident {* @term}) {? as @simple_intropattern} + specialize @ident with @bindings_list {? as @simple_intropattern} + :name: specialize; _ + + This tactic works on local hypothesis :n:`@ident`. The + premises of this hypothesis (either universal quantifications or + non-dependent implications) are instantiated by concrete terms coming either + from arguments :n:`{* @term}` or from a :ref:`bindings list <bindingslist>`. + In the first form the application to :n:`{* @term}` can be partial. The + first form is equivalent to :n:`assert (@ident := @ident {* @term})`. In the + second form, instantiation elements can also be partial. In this case the + uninstantiated arguments are inferred by unification if possible or left + quantified in the hypothesis otherwise. With the :n:`as` clause, the local + hypothesis :n:`@ident` is left unchanged and instead, the modified hypothesis + is introduced as specified by the :token:`simple_intropattern`. The name :n:`@ident` + can also refer to a global lemma or hypothesis. In this case, for + compatibility reasons, the behavior of :tacn:`specialize` is close to that of + :tacn:`generalize`: the instantiated statement becomes an additional premise of + the goal. The ``as`` clause is especially useful in this case to immediately + introduce the instantiated statement as a local hypothesis. + + .. exn:: @ident is used in hypothesis @ident. + :undocumented: + + .. exn:: @ident is used in conclusion. + :undocumented: + +.. tacn:: generalize @term + :name: generalize + + This tactic applies to any goal. It generalizes the conclusion with + respect to some term. + +.. example:: + + .. coqtop:: reset none + + Goal forall x y:nat, 0 <= x + y + y. + Proof. intros *. + + .. coqtop:: all + + Show. + generalize (x + y + y). + +If the goal is :g:`G` and :g:`t` is a subterm of type :g:`T` in the goal, +then :n:`generalize t` replaces the goal by :g:`forall (x:T), G′` where :g:`G′` +is obtained from :g:`G` by replacing all occurrences of :g:`t` by :g:`x`. The +name of the variable (here :g:`n`) is chosen based on :g:`T`. + +.. tacv:: generalize {+ @term} + + This is equivalent to :n:`generalize @term; ... ; generalize @term`. + Note that the sequence of term :sub:`i` 's are processed from n to 1. + +.. tacv:: generalize @term at {+ @num} + + This is equivalent to :n:`generalize @term` but it generalizes only over the + specified occurrences of :n:`@term` (counting from left to right on the + expression printed using option :flag:`Printing All`). + +.. tacv:: generalize @term as @ident + + This is equivalent to :n:`generalize @term` but it uses :n:`@ident` to name + the generalized hypothesis. + +.. tacv:: generalize {+, @term at {+ @num} as @ident} + + This is the most general form of :n:`generalize` that combines the previous + behaviors. + +.. tacv:: generalize dependent @term + + This generalizes term but also *all* hypotheses that depend on :n:`@term`. It + clears the generalized hypotheses. + +.. tacn:: evar (@ident : @term) + :name: evar + + The :n:`evar` tactic creates a new local definition named :n:`@ident` with type + :n:`@term` in the context. The body of this binding is a fresh existential + variable. + +.. tacn:: instantiate (@ident := @term ) + :name: instantiate + + The instantiate tactic refines (see :tacn:`refine`) an existential variable + :n:`@ident` with the term :n:`@term`. It is equivalent to only [ident]: + :n:`refine @term` (preferred alternative). + + .. note:: To be able to refer to an existential variable by name, the user + must have given the name explicitly (see :ref:`Existential-Variables`). + + .. note:: When you are referring to hypotheses which you did not name + explicitly, be aware that Coq may make a different decision on how to + name the variable in the current goal and in the context of the + existential variable. This can lead to surprising behaviors. + +.. tacv:: instantiate (@num := @term) + + This variant allows to refer to an existential variable which was not named + by the user. The :n:`@num` argument is the position of the existential variable + from right to left in the goal. Because this variant is not robust to slight + changes in the goal, its use is strongly discouraged. + +.. tacv:: instantiate ( @num := @term ) in @ident + instantiate ( @num := @term ) in ( value of @ident ) + instantiate ( @num := @term ) in ( type of @ident ) + + These allow to refer respectively to existential variables occurring in a + hypothesis or in the body or the type of a local definition. + +.. tacv:: instantiate + + Without argument, the instantiate tactic tries to solve as many existential + variables as possible, using information gathered from other tactics in the + same tactical. This is automatically done after each complete tactic (i.e. + after a dot in proof mode), but not, for example, between each tactic when + they are sequenced by semicolons. + +.. tacn:: admit + :name: admit + + This tactic allows temporarily skipping a subgoal so as to + progress further in the rest of the proof. A proof containing admitted + goals cannot be closed with :cmd:`Qed` but only with :cmd:`Admitted`. + +.. tacv:: give_up + + Synonym of :tacn:`admit`. + +.. tacn:: absurd @term + :name: absurd + + This tactic applies to any goal. The argument term is any proposition + :g:`P` of type :g:`Prop`. This tactic applies False elimination, that is it + deduces the current goal from False, and generates as subgoals :g:`∼P` and + :g:`P`. It is very useful in proofs by cases, where some cases are + impossible. In most cases, :g:`P` or :g:`∼P` is one of the hypotheses of the + local context. + +.. tacn:: contradiction + :name: contradiction + + This tactic applies to any goal. The contradiction tactic attempts to + find in the current context (after all intros) a hypothesis that is + equivalent to an empty inductive type (e.g. :g:`False`), to the negation of + a singleton inductive type (e.g. :g:`True` or :g:`x=x`), or two contradictory + hypotheses. + + .. exn:: No such assumption. + :undocumented: + +.. tacv:: contradiction @ident + + The proof of False is searched in the hypothesis named :n:`@ident`. + +.. tacn:: contradict @ident + :name: contradict + + This tactic allows manipulating negated hypothesis and goals. The name + :n:`@ident` should correspond to a hypothesis. With :n:`contradict H`, the + current goal and context is transformed in the following way: + + + H:¬A ⊢ B becomes ⊢ A + + H:¬A ⊢ ¬B becomes H: B ⊢ A + + H: A ⊢ B becomes ⊢ ¬A + + H: A ⊢ ¬B becomes H: B ⊢ ¬A + +.. tacn:: exfalso + :name: exfalso + + This tactic implements the “ex falso quodlibet” logical principle: an + elimination of False is performed on the current goal, and the user is + then required to prove that False is indeed provable in the current + context. This tactic is a macro for :n:`elimtype False`. + +.. _CaseAnalysisAndInduction: + +Case analysis and induction +------------------------------- + +The tactics presented in this section implement induction or case +analysis on inductive or co-inductive objects (see :ref:`inductive-definitions`). + +.. tacn:: destruct @term + :name: destruct + + This tactic applies to any goal. The argument :token:`term` must be of + inductive or co-inductive type and the tactic generates subgoals, one + for each possible form of :token:`term`, i.e. one for each constructor of the + inductive or co-inductive type. Unlike :tacn:`induction`, no induction + hypothesis is generated by :tacn:`destruct`. + + .. tacv:: destruct @ident + + If :token:`ident` denotes a quantified variable of the conclusion + of the goal, then :n:`destruct @ident` behaves + as :n:`intros until @ident; destruct @ident`. If :token:`ident` is not + anymore dependent in the goal after application of :tacn:`destruct`, it + is erased (to avoid erasure, use parentheses, as in :n:`destruct (@ident)`). + + If :token:`ident` is a hypothesis of the context, and :token:`ident` + is not anymore dependent in the goal after application + of :tacn:`destruct`, it is erased (to avoid erasure, use parentheses, as + in :n:`destruct (@ident)`). + + .. tacv:: destruct @num + + :n:`destruct @num` behaves as :n:`intros until @num` + followed by destruct applied to the last introduced hypothesis. + + .. note:: + For destruction of a numeral, use syntax :n:`destruct (@num)` (not + very interesting anyway). + + .. tacv:: destruct @pattern + + The argument of :tacn:`destruct` can also be a pattern of which holes are + denoted by “_”. In this case, the tactic checks that all subterms + matching the pattern in the conclusion and the hypotheses are compatible + and performs case analysis using this subterm. + + .. tacv:: destruct {+, @term} + + This is a shortcut for :n:`destruct @term; ...; destruct @term`. + + .. tacv:: destruct @term as @or_and_intropattern_loc + + This behaves as :n:`destruct @term` but uses the names + in :token:`or_and_intropattern_loc` to name the variables introduced in the + context. The :token:`or_and_intropattern_loc` must have the + form :n:`[p11 ... p1n | ... | pm1 ... pmn ]` with ``m`` being the + number of constructors of the type of :token:`term`. Each variable + introduced by :tacn:`destruct` in the context of the ``i``-th goal + gets its name from the list :n:`pi1 ... pin` in order. If there are not + enough names, :tacn:`destruct` invents names for the remaining variables + to introduce. More generally, the :n:`pij` can be any introduction + pattern (see :tacn:`intros`). This provides a concise notation for + chaining destruction of a hypothesis. + + .. tacv:: destruct @term eqn:@naming_intropattern + :name: destruct ... eqn: + + This behaves as :n:`destruct @term` but adds an equation + between :token:`term` and the value that it takes in each of the + possible cases. The name of the equation is specified + by :token:`naming_intropattern` (see :tacn:`intros`), + in particular ``?`` can be used to let Coq generate a fresh name. + + .. tacv:: destruct @term with @bindings_list + + This behaves like :n:`destruct @term` providing explicit instances for + the dependent premises of the type of :token:`term`. + + .. tacv:: edestruct @term + :name: edestruct + + This tactic behaves like :n:`destruct @term` except that it does not + fail if the instance of a dependent premises of the type + of :token:`term` is not inferable. Instead, the unresolved instances + are left as existential variables to be inferred later, in the same way + as :tacn:`eapply` does. + + .. tacv:: destruct @term using @term {? with @bindings_list } + + This is synonym of :n:`induction @term using @term {? with @bindings_list }`. + + .. tacv:: destruct @term in @goal_occurrences + + This syntax is used for selecting which occurrences of :token:`term` + the case analysis has to be done on. The :n:`in @goal_occurrences` + clause is an occurrence clause whose syntax and behavior is described + in :ref:`occurrences sets <occurrencessets>`. + + .. tacv:: destruct @term {? with @bindings_list } {? as @or_and_intropattern_loc } {? eqn:@naming_intropattern } {? using @term {? with @bindings_list } } {? in @goal_occurrences } + edestruct @term {? with @bindings_list } {? as @or_and_intropattern_loc } {? eqn:@naming_intropattern } {? using @term {? with @bindings_list } } {? in @goal_occurrences } + + These are the general forms of :tacn:`destruct` and :tacn:`edestruct`. + They combine the effects of the ``with``, ``as``, ``eqn:``, ``using``, + and ``in`` clauses. + +.. tacn:: case term + :name: case + + The tactic :n:`case` is a more basic tactic to perform case analysis without + recursion. It behaves as :n:`elim @term` but using a case-analysis + elimination principle and not a recursive one. + +.. tacv:: case @term with @bindings_list + + Analogous to :n:`elim @term with @bindings_list` above. + +.. tacv:: ecase @term {? with @bindings_list } + :name: ecase + + In case the type of :n:`@term` has dependent premises, or dependent premises + whose values are not inferable from the :n:`with @bindings_list` clause, + :n:`ecase` turns them into existential variables to be resolved later on. + +.. tacv:: simple destruct @ident + :name: simple destruct + + This tactic behaves as :n:`intros until @ident; case @ident` when :n:`@ident` + is a quantified variable of the goal. + +.. tacv:: simple destruct @num + + This tactic behaves as :n:`intros until @num; case @ident` where :n:`@ident` + is the name given by :n:`intros until @num` to the :n:`@num` -th + non-dependent premise of the goal. + +.. tacv:: case_eq @term + + The tactic :n:`case_eq` is a variant of the :n:`case` tactic that allows to + perform case analysis on a term without completely forgetting its original + form. This is done by generating equalities between the original form of the + term and the outcomes of the case analysis. + +.. tacn:: induction @term + :name: induction + + This tactic applies to any goal. The argument :n:`@term` must be of + inductive type and the tactic :n:`induction` generates subgoals, one for + each possible form of :n:`@term`, i.e. one for each constructor of the + inductive type. + + If the argument is dependent in either the conclusion or some + hypotheses of the goal, the argument is replaced by the appropriate + constructor form in each of the resulting subgoals and induction + hypotheses are added to the local context using names whose prefix + is **IH**. + + There are particular cases: + + + If term is an identifier :n:`@ident` denoting a quantified variable of the + conclusion of the goal, then inductionident behaves as :n:`intros until + @ident; induction @ident`. If :n:`@ident` is not anymore dependent in the + goal after application of :n:`induction`, it is erased (to avoid erasure, + use parentheses, as in :n:`induction (@ident)`). + + If :n:`@term` is a :n:`@num`, then :n:`induction @num` behaves as + :n:`intros until @num` followed by :n:`induction` applied to the last + introduced hypothesis. + + .. note:: + For simple induction on a numeral, use syntax induction (num) + (not very interesting anyway). + + + In case term is a hypothesis :n:`@ident` of the context, and :n:`@ident` + is not anymore dependent in the goal after application of :n:`induction`, + it is erased (to avoid erasure, use parentheses, as in + :n:`induction (@ident)`). + + The argument :n:`@term` can also be a pattern of which holes are denoted + by “_”. In this case, the tactic checks that all subterms matching the + pattern in the conclusion and the hypotheses are compatible and + performs induction using this subterm. + +.. example:: + + .. coqtop:: reset all + + Lemma induction_test : forall n:nat, n = n -> n <= n. + intros n H. + induction n. + +.. exn:: Not an inductive product. + :undocumented: + +.. exn:: Unable to find an instance for the variables @ident ... @ident. + + Use in this case the variant :tacn:`elim ... with` below. + +.. tacv:: induction @term as @or_and_intropattern_loc + + This behaves as :tacn:`induction` but uses the names in + :n:`@or_and_intropattern_loc` to name the variables introduced in the + context. The :n:`@or_and_intropattern_loc` must typically be of the form + :n:`[ p` :sub:`11` :n:`... p` :sub:`1n` :n:`| ... | p`:sub:`m1` :n:`... p`:sub:`mn` :n:`]` + with :n:`m` being the number of constructors of the type of :n:`@term`. Each + variable introduced by induction in the context of the i-th goal gets its + name from the list :n:`p`:sub:`i1` :n:`... p`:sub:`in` in order. If there are + not enough names, induction invents names for the remaining variables to + introduce. More generally, the :n:`p`:sub:`ij` can be any + disjunctive/conjunctive introduction pattern (see :tacn:`intros ...`). For + instance, for an inductive type with one constructor, the pattern notation + :n:`(p`:sub:`1` :n:`, ... , p`:sub:`n` :n:`)` can be used instead of + :n:`[ p`:sub:`1` :n:`... p`:sub:`n` :n:`]`. + +.. tacv:: induction @term with @bindings_list + + This behaves like :tacn:`induction` providing explicit instances for the + premises of the type of :n:`term` (see :ref:`bindings list <bindingslist>`). + +.. tacv:: einduction @term + :name: einduction + + This tactic behaves like :tacn:`induction` except that it does not fail if + some dependent premise of the type of :n:`@term` is not inferable. Instead, + the unresolved premises are posed as existential variables to be inferred + later, in the same way as :tacn:`eapply` does. + +.. tacv:: induction @term using @term + :name: induction ... using ... + + This behaves as :tacn:`induction` but using :n:`@term` as induction scheme. + It does not expect the conclusion of the type of the first :n:`@term` to be + inductive. + +.. tacv:: induction @term using @term with @bindings_list + + This behaves as :tacn:`induction ... using ...` but also providing instances + for the premises of the type of the second :n:`@term`. + +.. tacv:: induction {+, @term} using @qualid + + This syntax is used for the case :n:`@qualid` denotes an induction principle + with complex predicates as the induction principles generated by + ``Function`` or ``Functional Scheme`` may be. + +.. tacv:: induction @term in @goal_occurrences + + This syntax is used for selecting which occurrences of :n:`@term` the + induction has to be carried on. The :n:`in @goal_occurrences` clause is an + occurrence clause whose syntax and behavior is described in + :ref:`occurrences sets <occurrencessets>`. If variables or hypotheses not + mentioning :n:`@term` in their type are listed in :n:`@goal_occurrences`, + those are generalized as well in the statement to prove. + + .. example:: + + .. coqtop:: reset all + + Lemma comm x y : x + y = y + x. + induction y in x |- *. + Show 2. + +.. tacv:: induction @term with @bindings_list as @or_and_intropattern_loc using @term with @bindings_list in @goal_occurrences + einduction @term with @bindings_list as @or_and_intropattern_loc using @term with @bindings_list in @goal_occurrences + + These are the most general forms of :tacn:`induction` and :tacn:`einduction`. It combines the + effects of the with, as, using, and in clauses. + +.. tacv:: elim @term + :name: elim + + This is a more basic induction tactic. Again, the type of the argument + :n:`@term` must be an inductive type. Then, according to the type of the + goal, the tactic ``elim`` chooses the appropriate destructor and applies it + as the tactic :tacn:`apply` would do. For instance, if the proof context + contains :g:`n:nat` and the current goal is :g:`T` of type :g:`Prop`, then + :n:`elim n` is equivalent to :n:`apply nat_ind with (n:=n)`. The tactic + ``elim`` does not modify the context of the goal, neither introduces the + induction loading into the context of hypotheses. More generally, + :n:`elim @term` also works when the type of :n:`@term` is a statement + with premises and whose conclusion is inductive. In that case the tactic + performs induction on the conclusion of the type of :n:`@term` and leaves the + non-dependent premises of the type as subgoals. In the case of dependent + products, the tactic tries to find an instance for which the elimination + lemma applies and fails otherwise. + +.. tacv:: elim @term with @bindings_list + :name: elim ... with + + Allows to give explicit instances to the premises of the type of :n:`@term` + (see :ref:`bindings list <bindingslist>`). + +.. tacv:: eelim @term + :name: eelim + + In case the type of :n:`@term` has dependent premises, this turns them into + existential variables to be resolved later on. + +.. tacv:: elim @term using @term + elim @term using @term with @bindings_list + + Allows the user to give explicitly an induction principle :n:`@term` that + is not the standard one for the underlying inductive type of :n:`@term`. The + :n:`@bindings_list` clause allows instantiating premises of the type of + :n:`@term`. + +.. tacv:: elim @term with @bindings_list using @term with @bindings_list + eelim @term with @bindings_list using @term with @bindings_list + + These are the most general forms of :tacn:`elim` and :tacn:`eelim`. It combines the + effects of the ``using`` clause and of the two uses of the ``with`` clause. + +.. tacv:: elimtype @type + :name: elimtype + + The argument :token:`type` must be inductively defined. :n:`elimtype I` is + equivalent to :n:`cut I. intro Hn; elim Hn; clear Hn.` Therefore the + hypothesis :g:`Hn` will not appear in the context(s) of the subgoal(s). + Conversely, if :g:`t` is a :n:`@term` of (inductive) type :g:`I` that does + not occur in the goal, then :n:`elim t` is equivalent to + :n:`elimtype I; 2:exact t.` + +.. tacv:: simple induction @ident + :name: simple induction + + This tactic behaves as :n:`intros until @ident; elim @ident` when + :n:`@ident` is a quantified variable of the goal. + +.. tacv:: simple induction @num + + This tactic behaves as :n:`intros until @num; elim @ident` where :n:`@ident` + is the name given by :n:`intros until @num` to the :n:`@num`-th non-dependent + premise of the goal. + +.. tacn:: double induction @ident @ident + :name: double induction + + This tactic is deprecated and should be replaced by + :n:`induction @ident; induction @ident` (or + :n:`induction @ident ; destruct @ident` depending on the exact needs). + +.. tacv:: double induction num1 num2 + + This tactic is deprecated and should be replaced by + :n:`induction num1; induction num3` where :n:`num3` is the result + of :n:`num2 - num1` + +.. tacn:: dependent induction @ident + :name: dependent induction + + The *experimental* tactic dependent induction performs induction- + inversion on an instantiated inductive predicate. One needs to first + require the Coq.Program.Equality module to use this tactic. The tactic + is based on the BasicElim tactic by Conor McBride + :cite:`DBLP:conf/types/McBride00` and the work of Cristina Cornes around + inversion :cite:`DBLP:conf/types/CornesT95`. From an instantiated + inductive predicate and a goal, it generates an equivalent goal where + the hypothesis has been generalized over its indexes which are then + constrained by equalities to be the right instances. This permits to + state lemmas without resorting to manually adding these equalities and + still get enough information in the proofs. + +.. example:: + + .. coqtop:: reset all + + Lemma le_minus : forall n:nat, n < 1 -> n = 0. + intros n H ; induction H. + + Here we did not get any information on the indexes to help fulfill + this proof. The problem is that, when we use the ``induction`` tactic, we + lose information on the hypothesis instance, notably that the second + argument is 1 here. Dependent induction solves this problem by adding + the corresponding equality to the context. + + .. coqtop:: reset all + + Require Import Coq.Program.Equality. + Lemma le_minus : forall n:nat, n < 1 -> n = 0. + intros n H ; dependent induction H. + + The subgoal is cleaned up as the tactic tries to automatically + simplify the subgoals with respect to the generated equalities. In + this enriched context, it becomes possible to solve this subgoal. + + .. coqtop:: all + + reflexivity. + + Now we are in a contradictory context and the proof can be solved. + + .. coqtop:: all + + inversion H. + + This technique works with any inductive predicate. In fact, the + ``dependent induction`` tactic is just a wrapper around the ``induction`` + tactic. One can make its own variant by just writing a new tactic + based on the definition found in ``Coq.Program.Equality``. + +.. tacv:: dependent induction @ident generalizing {+ @ident} + + This performs dependent induction on the hypothesis :n:`@ident` but first + generalizes the goal by the given variables so that they are universally + quantified in the goal. This is generally what one wants to do with the + variables that are inside some constructors in the induction hypothesis. The + other ones need not be further generalized. + +.. tacv:: dependent destruction @ident + :name: dependent destruction + + This performs the generalization of the instance :n:`@ident` but uses + ``destruct`` instead of induction on the generalized hypothesis. This gives + results equivalent to ``inversion`` or ``dependent inversion`` if the + hypothesis is dependent. + +See also the larger example of :tacn:`dependent induction` +and an explanation of the underlying technique. + +.. tacn:: function induction (@qualid {+ @term}) + :name: function induction + + The tactic functional induction performs case analysis and induction + following the definition of a function. It makes use of a principle + generated by ``Function`` (see :ref:`advanced-recursive-functions`) or + ``Functional Scheme`` (see :ref:`functional-scheme`). + Note that this tactic is only available after a ``Require Import FunInd``. + +.. example:: + + .. coqtop:: reset all + + Require Import FunInd. + Functional Scheme minus_ind := Induction for minus Sort Prop. + Check minus_ind. + Lemma le_minus (n m:nat) : n - m <= n. + functional induction (minus n m) using minus_ind; simpl; auto. + Qed. + +.. note:: + :n:`(@qualid {+ @term})` must be a correct full application + of :n:`@qualid`. In particular, the rules for implicit arguments are the + same as usual. For example use :n:`@qualid` if you want to write implicit + arguments explicitly. + +.. note:: + Parentheses around :n:`@qualid {+ @term}` are not mandatory and can be skipped. + +.. note:: + :n:`functional induction (f x1 x2 x3)` is actually a wrapper for + :n:`induction x1, x2, x3, (f x1 x2 x3) using @qualid` followed by a cleaning + phase, where :n:`@qualid` is the induction principle registered for :g:`f` + (by the ``Function`` (see :ref:`advanced-recursive-functions`) or + ``Functional Scheme`` (see :ref:`functional-scheme`) + command) corresponding to the sort of the goal. Therefore + ``functional induction`` may fail if the induction scheme :n:`@qualid` is not + defined. See also :ref:`advanced-recursive-functions` for the function + terms accepted by ``Function``. + +.. note:: + There is a difference between obtaining an induction scheme + for a function by using :g:`Function` (see :ref:`advanced-recursive-functions`) + and by using :g:`Functional Scheme` after a normal definition using + :g:`Fixpoint` or :g:`Definition`. See :ref:`advanced-recursive-functions` + for details. + +.. seealso:: :ref:`advanced-recursive-functions`, :ref:`functional-scheme` and :tacn:`inversion` + +.. exn:: Cannot find induction information on @qualid. + :undocumented: + +.. exn:: Not the right number of induction arguments. + :undocumented: + +.. tacv:: functional induction (@qualid {+ @term}) as @simple_intropattern using @term with @bindings_list + + Similarly to :tacn:`induction` and :tacn:`elim`, this allows giving + explicitly the name of the introduced variables, the induction principle, and + the values of dependent premises of the elimination scheme, including + *predicates* for mutual induction when :n:`@qualid` is part of a mutually + recursive definition. + +.. tacn:: discriminate @term + :name: discriminate + + This tactic proves any goal from an assumption stating that two + structurally different :n:`@terms` of an inductive set are equal. For + example, from :g:`(S (S O))=(S O)` we can derive by absurdity any + proposition. + + The argument :n:`@term` is assumed to be a proof of a statement of + conclusion :n:`@term = @term` with the two terms being elements of an + inductive set. To build the proof, the tactic traverses the normal forms + [3]_ of the terms looking for a couple of subterms :g:`u` and :g:`w` (:g:`u` + subterm of the normal form of :n:`@term` and :g:`w` subterm of the normal + form of :n:`@term`), placed at the same positions and whose head symbols are + two different constructors. If such a couple of subterms exists, then the + proof of the current goal is completed, otherwise the tactic fails. + +.. note:: + The syntax :n:`discriminate @ident` can be used to refer to a hypothesis + quantified in the goal. In this case, the quantified hypothesis whose name is + :n:`@ident` is first introduced in the local context using + :n:`intros until @ident`. + +.. exn:: No primitive equality found. + :undocumented: + +.. exn:: Not a discriminable equality. + :undocumented: + +.. tacv:: discriminate @num + + This does the same thing as :n:`intros until @num` followed by + :n:`discriminate @ident` where :n:`@ident` is the identifier for the last + introduced hypothesis. + +.. tacv:: discriminate @term with @bindings_list + + This does the same thing as :n:`discriminate @term` but using the given + bindings to instantiate parameters or hypotheses of :n:`@term`. + +.. tacv:: ediscriminate @num + ediscriminate @term {? with @bindings_list} + :name: ediscriminate; _ + + This works the same as :tacn:`discriminate` but if the type of :token:`term`, or the + type of the hypothesis referred to by :token:`num`, has uninstantiated + parameters, these parameters are left as existential variables. + +.. tacv:: discriminate + + This behaves like :n:`discriminate @ident` if ident is the name of an + hypothesis to which ``discriminate`` is applicable; if the current goal is of + the form :n:`@term <> @term`, this behaves as + :n:`intro @ident; discriminate @ident`. + + .. exn:: No discriminable equalities. + :undocumented: + +.. tacn:: injection @term + :name: injection + + The injection tactic exploits the property that constructors of + inductive types are injective, i.e. that if :g:`c` is a constructor of an + inductive type and :g:`c t`:sub:`1` and :g:`c t`:sub:`2` are equal then + :g:`t`:sub:`1` and :g:`t`:sub:`2` are equal too. + + If :n:`@term` is a proof of a statement of conclusion :n:`@term = @term`, + then :tacn:`injection` applies the injectivity of constructors as deep as + possible to derive the equality of all the subterms of :n:`@term` and + :n:`@term` at positions where the terms start to differ. For example, from + :g:`(S p, S n) = (q, S (S m))` we may derive :g:`S p = q` and + :g:`n = S m`. For this tactic to work, the terms should be typed with an + inductive type and they should be neither convertible, nor having a different + head constructor. If these conditions are satisfied, the tactic derives the + equality of all the subterms at positions where they differ and adds them as + antecedents to the conclusion of the current goal. + + .. example:: + + Consider the following goal: + + .. coqtop:: in + + Inductive list : Set := + | nil : list + | cons : nat -> list -> list. + Parameter P : list -> Prop. + Goal forall l n, P nil -> cons n l = cons 0 nil -> P l. + + .. coqtop:: all + + intros. + injection H0. + + Beware that injection yields an equality in a sigma type whenever the + injected object has a dependent type :g:`P` with its two instances in + different types :g:`(P t`:sub:`1` :g:`... t`:sub:`n` :g:`)` and + :g:`(P u`:sub:`1` :g:`... u`:sub:`n` :sub:`)`. If :g:`t`:sub:`1` and + :g:`u`:sub:`1` are the same and have for type an inductive type for which a decidable + equality has been declared using the command :cmd:`Scheme Equality` + (see :ref:`proofschemes-induction-principles`), + the use of a sigma type is avoided. + + .. note:: + If some quantified hypothesis of the goal is named :n:`@ident`, + then :n:`injection @ident` first introduces the hypothesis in the local + context using :n:`intros until @ident`. + + .. exn:: Not a projectable equality but a discriminable one. + :undocumented: + + .. exn:: Nothing to do, it is an equality between convertible terms. + :undocumented: + + .. exn:: Not a primitive equality. + :undocumented: + + .. exn:: Nothing to inject. + :undocumented: + + .. tacv:: injection @num + + This does the same thing as :n:`intros until @num` followed by + :n:`injection @ident` where :n:`@ident` is the identifier for the last + introduced hypothesis. + + .. tacv:: injection @term with @bindings_list + + This does the same as :n:`injection @term` but using the given bindings to + instantiate parameters or hypotheses of :n:`@term`. + + .. tacv:: einjection @num + einjection @term {? with @bindings_list} + :name: einjection; _ + + This works the same as :n:`injection` but if the type of :n:`@term`, or the + type of the hypothesis referred to by :n:`@num`, has uninstantiated + parameters, these parameters are left as existential variables. + + .. tacv:: injection + + If the current goal is of the form :n:`@term <> @term` , this behaves as + :n:`intro @ident; injection @ident`. + + .. exn:: goal does not satisfy the expected preconditions. + :undocumented: + + .. tacv:: injection @term {? with @bindings_list} as {+ @simple_intropattern} + injection @num as {+ simple_intropattern} + injection as {+ simple_intropattern} + einjection @term {? with @bindings_list} as {+ simple_intropattern} + einjection @num as {+ simple_intropattern} + einjection as {+ simple_intropattern} + + These variants apply :n:`intros {+ @simple_intropattern}` after the call to + :tacn:`injection` or :tacn:`einjection` so that all equalities generated are moved in + the context of hypotheses. The number of :n:`@simple_intropattern` must not exceed + the number of equalities newly generated. If it is smaller, fresh + names are automatically generated to adjust the list of :n:`@simple_intropattern` + to the number of new equalities. The original equality is erased if it + corresponds to a hypothesis. + + .. flag:: Structural Injection + + This option ensure that :n:`injection @term` erases the original hypothesis + and leaves the generated equalities in the context rather than putting them + as antecedents of the current goal, as if giving :n:`injection @term as` + (with an empty list of names). This option is off by default. + + .. flag:: Keep Proof Equalities + + By default, :tacn:`injection` only creates new equalities between :n:`@terms` + whose type is in sort :g:`Type` or :g:`Set`, thus implementing a special + behavior for objects that are proofs of a statement in :g:`Prop`. This option + controls this behavior. + +.. tacn:: inversion @ident + :name: inversion + + Let the type of :n:`@ident` in the local context be :g:`(I t)`, where :g:`I` + is a (co)inductive predicate. Then, ``inversion`` applied to :n:`@ident` + derives for each possible constructor :g:`c i` of :g:`(I t)`, all the + necessary conditions that should hold for the instance :g:`(I t)` to be + proved by :g:`c i`. + +.. note:: + If :n:`@ident` does not denote a hypothesis in the local context but + refers to a hypothesis quantified in the goal, then the latter is + first introduced in the local context using :n:`intros until @ident`. + +.. note:: + As ``inversion`` proofs may be large in size, we recommend the + user to stock the lemmas whenever the same instance needs to be + inverted several times. See :ref:`derive-inversion`. + +.. note:: + Part of the behavior of the ``inversion`` tactic is to generate + equalities between expressions that appeared in the hypothesis that is + being processed. By default, no equalities are generated if they + relate two proofs (i.e. equalities between :token:`term`\s whose type is in sort + :g:`Prop`). This behavior can be turned off by using the + :flag:`Keep Proof Equalities` setting. + +.. tacv:: inversion @num + + This does the same thing as :n:`intros until @num` then :n:`inversion @ident` + where :n:`@ident` is the identifier for the last introduced hypothesis. + +.. tacv:: inversion_clear @ident + :name: inversion_clear + + This behaves as :n:`inversion` and then erases :n:`@ident` from the context. + +.. tacv:: inversion @ident as @or_and_intropattern_loc + + This generally behaves as inversion but using names in :n:`@or_and_intropattern_loc` + for naming hypotheses. The :n:`@or_and_intropattern_loc` must have the form + :n:`[p`:sub:`11` :n:`... p`:sub:`1n` :n:`| ... | p`:sub:`m1` :n:`... p`:sub:`mn` :n:`]` + with `m` being the number of constructors of the type of :n:`@ident`. Be + careful that the list must be of length `m` even if ``inversion`` discards + some cases (which is precisely one of its roles): for the discarded + cases, just use an empty list (i.e. `n = 0`).The arguments of the i-th + constructor and the equalities that ``inversion`` introduces in the + context of the goal corresponding to the i-th constructor, if it + exists, get their names from the list :n:`p`:sub:`i1` :n:`... p`:sub:`in` in + order. If there are not enough names, ``inversion`` invents names for the + remaining variables to introduce. In case an equation splits into several + equations (because ``inversion`` applies ``injection`` on the equalities it + generates), the corresponding name :n:`p`:sub:`ij` in the list must be + replaced by a sublist of the form :n:`[p`:sub:`ij1` :n:`... p`:sub:`ijq` :n:`]` + (or, equivalently, :n:`(p`:sub:`ij1` :n:`, ..., p`:sub:`ijq` :n:`)`) where + `q` is the number of subequalities obtained from splitting the original + equation. Here is an example. The ``inversion ... as`` variant of + ``inversion`` generally behaves in a slightly more expectable way than + ``inversion`` (no artificial duplication of some hypotheses referring to + other hypotheses). To take benefit of these improvements, it is enough to use + ``inversion ... as []``, letting the names being finally chosen by Coq. + + .. example:: + + .. coqtop:: reset all + + Inductive contains0 : list nat -> Prop := + | in_hd : forall l, contains0 (0 :: l) + | in_tl : forall l b, contains0 l -> contains0 (b :: l). + Goal forall l:list nat, contains0 (1 :: l) -> contains0 l. + intros l H; inversion H as [ | l' p Hl' [Heqp Heql'] ]. + +.. tacv:: inversion @num as @or_and_intropattern_loc + + This allows naming the hypotheses introduced by :n:`inversion @num` in the + context. + +.. tacv:: inversion_clear @ident as @or_and_intropattern_loc + + This allows naming the hypotheses introduced by ``inversion_clear`` in the + context. Notice that hypothesis names can be provided as if ``inversion`` + were called, even though the ``inversion_clear`` will eventually erase the + hypotheses. + +.. tacv:: inversion @ident in {+ @ident} + + Let :n:`{+ @ident}` be identifiers in the local context. This tactic behaves as + generalizing :n:`{+ @ident}`, and then performing ``inversion``. + +.. tacv:: inversion @ident as @or_and_intropattern_loc in {+ @ident} + + This allows naming the hypotheses introduced in the context by + :n:`inversion @ident in {+ @ident}`. + +.. tacv:: inversion_clear @ident in {+ @ident} + + Let :n:`{+ @ident}` be identifiers in the local context. This tactic behaves + as generalizing :n:`{+ @ident}`, and then performing ``inversion_clear``. + +.. tacv:: inversion_clear @ident as @or_and_intropattern_loc in {+ @ident} + + This allows naming the hypotheses introduced in the context by + :n:`inversion_clear @ident in {+ @ident}`. + +.. tacv:: dependent inversion @ident + :name: dependent inversion + + That must be used when :n:`@ident` appears in the current goal. It acts like + ``inversion`` and then substitutes :n:`@ident` for the corresponding + :n:`@@term` in the goal. + +.. tacv:: dependent inversion @ident as @or_and_intropattern_loc + + This allows naming the hypotheses introduced in the context by + :n:`dependent inversion @ident`. + +.. tacv:: dependent inversion_clear @ident + + Like ``dependent inversion``, except that :n:`@ident` is cleared from the + local context. + +.. tacv:: dependent inversion_clear @ident as @or_and_intropattern_loc + + This allows naming the hypotheses introduced in the context by + :n:`dependent inversion_clear @ident`. + +.. tacv:: dependent inversion @ident with @term + :name: dependent inversion ... with ... + + This variant allows you to specify the generalization of the goal. It is + useful when the system fails to generalize the goal automatically. If + :n:`@ident` has type :g:`(I t)` and :g:`I` has type :g:`forall (x:T), s`, + then :n:`@term` must be of type :g:`I:forall (x:T), I x -> s'` where + :g:`s'` is the type of the goal. + +.. tacv:: dependent inversion @ident as @or_and_intropattern_loc with @term + + This allows naming the hypotheses introduced in the context by + :n:`dependent inversion @ident with @term`. + +.. tacv:: dependent inversion_clear @ident with @term + + Like :tacn:`dependent inversion ... with ...` with but clears :n:`@ident` from the + local context. + +.. tacv:: dependent inversion_clear @ident as @or_and_intropattern_loc with @term + + This allows naming the hypotheses introduced in the context by + :n:`dependent inversion_clear @ident with @term`. + +.. tacv:: simple inversion @ident + :name: simple inversion + + It is a very primitive inversion tactic that derives all the necessary + equalities but it does not simplify the constraints as ``inversion`` does. + +.. tacv:: simple inversion @ident as @or_and_intropattern_loc + + This allows naming the hypotheses introduced in the context by + ``simple inversion``. + +.. tacv:: inversion @ident using @ident + :name: inversion ... using ... + + Let :n:`@ident` have type :g:`(I t)` (:g:`I` an inductive predicate) in the + local context, and :n:`@ident` be a (dependent) inversion lemma. Then, this + tactic refines the current goal with the specified lemma. + +.. tacv:: inversion @ident using @ident in {+ @ident} + + This tactic behaves as generalizing :n:`{+ @ident}`, then doing + :n:`inversion @ident using @ident`. + +.. tacv:: inversion_sigma + :name: inversion_sigma + + This tactic turns equalities of dependent pairs (e.g., + :g:`existT P x p = existT P y q`, frequently left over by inversion on + a dependent type family) into pairs of equalities (e.g., a hypothesis + :g:`H : x = y` and a hypothesis of type :g:`rew H in p = q`); these + hypotheses can subsequently be simplified using :tacn:`subst`, without ever + invoking any kind of axiom asserting uniqueness of identity proofs. If you + want to explicitly specify the hypothesis to be inverted, or name the + generated hypotheses, you can invoke + :n:`induction H as [H1 H2] using eq_sigT_rect.` This tactic also works for + :g:`sig`, :g:`sigT2`, and :g:`sig2`, and there are similar :g:`eq_sig` + :g:`***_rect` induction lemmas. + +.. example:: + + *Non-dependent inversion*. + + Let us consider the relation :g:`Le` over natural numbers: + + .. coqtop:: reset in + + Inductive Le : nat -> nat -> Set := + | LeO : forall n:nat, Le 0 n + | LeS : forall n m:nat, Le n m -> Le (S n) (S m). + + + Let us consider the following goal: + + .. coqtop:: none + + Section Section. + Variable P : nat -> nat -> Prop. + Variable Q : forall n m:nat, Le n m -> Prop. + Goal forall n m, Le (S n) m -> P n m. + + .. coqtop:: out + + intros. + + To prove the goal, we may need to reason by cases on :g:`H` and to derive + that :g:`m` is necessarily of the form :g:`(S m0)` for certain :g:`m0` and that + :g:`(Le n m0)`. Deriving these conditions corresponds to proving that the only + possible constructor of :g:`(Le (S n) m)` is :g:`LeS` and that we can invert + the arrow in the type of :g:`LeS`. This inversion is possible because :g:`Le` + is the smallest set closed by the constructors :g:`LeO` and :g:`LeS`. + + .. coqtop:: all + + inversion_clear H. + + Note that :g:`m` has been substituted in the goal for :g:`(S m0)` and that the + hypothesis :g:`(Le n m0)` has been added to the context. + + Sometimes it is interesting to have the equality :g:`m = (S m0)` in the + context to use it after. In that case we can use :tacn:`inversion` that does + not clear the equalities: + + .. coqtop:: none restart + + intros. + + .. coqtop:: all + + inversion H. + +.. example:: + + *Dependent inversion.* + + Let us consider the following goal: + + .. coqtop:: none + + Abort. + Goal forall n m (H:Le (S n) m), Q (S n) m H. + + .. coqtop:: out + + intros. + + As :g:`H` occurs in the goal, we may want to reason by cases on its + structure and so, we would like inversion tactics to substitute :g:`H` by + the corresponding @term in constructor form. Neither :tacn:`inversion` nor + :tacn:`inversion_clear` do such a substitution. To have such a behavior we + use the dependent inversion tactics: + + .. coqtop:: all + + dependent inversion_clear H. + + Note that :g:`H` has been substituted by :g:`(LeS n m0 l)` and :g:`m` by :g:`(S m0)`. + +.. example:: + + *Using inversion_sigma.* + + Let us consider the following inductive type of + length-indexed lists, and a lemma about inverting equality of cons: + + .. coqtop:: reset all + + Require Import Coq.Logic.Eqdep_dec. + + Inductive vec A : nat -> Type := + | nil : vec A O + | cons {n} (x : A) (xs : vec A n) : vec A (S n). + + Lemma invert_cons : forall A n x xs y ys, + @cons A n x xs = @cons A n y ys + -> xs = ys. + + Proof. + intros A n x xs y ys H. + + After performing inversion, we are left with an equality of existTs: + + .. coqtop:: all + + inversion H. + + We can turn this equality into a usable form with inversion_sigma: + + .. coqtop:: all + + inversion_sigma. + + To finish cleaning up the proof, we will need to use the fact that + that all proofs of n = n for n a nat are eq_refl: + + .. coqtop:: all + + let H := match goal with H : n = n |- _ => H end in + pose proof (Eqdep_dec.UIP_refl_nat _ H); subst H. + simpl in *. + + Finally, we can finish the proof: + + .. coqtop:: all + + assumption. + Qed. + +.. tacn:: fix @ident @num + :name: fix + + This tactic is a primitive tactic to start a proof by induction. In + general, it is easier to rely on higher-level induction tactics such + as the ones described in :tacn:`induction`. + + In the syntax of the tactic, the identifier :n:`@ident` is the name given to + the induction hypothesis. The natural number :n:`@num` tells on which + premise of the current goal the induction acts, starting from 1, + counting both dependent and non dependent products, but skipping local + definitions. Especially, the current lemma must be composed of at + least :n:`@num` products. + + Like in a fix expression, the induction hypotheses have to be used on + structurally smaller arguments. The verification that inductive proof + arguments are correct is done only at the time of registering the + lemma in the environment. To know if the use of induction hypotheses + is correct at some time of the interactive development of a proof, use + the command ``Guarded`` (see Section :ref:`requestinginformation`). + +.. tacv:: fix @ident @num with {+ (ident {+ @binder} [{struct @ident}] : @type)} + + This starts a proof by mutual induction. The statements to be simultaneously + proved are respectively :g:`forall binder ... binder, type`. + The identifiers :n:`@ident` are the names of the induction hypotheses. The identifiers + :n:`@ident` are the respective names of the premises on which the induction + is performed in the statements to be simultaneously proved (if not given, the + system tries to guess itself what they are). + +.. tacn:: cofix @ident + :name: cofix + + This tactic starts a proof by coinduction. The identifier :n:`@ident` is the + name given to the coinduction hypothesis. Like in a cofix expression, + the use of induction hypotheses have to guarded by a constructor. The + verification that the use of co-inductive hypotheses is correct is + done only at the time of registering the lemma in the environment. To + know if the use of coinduction hypotheses is correct at some time of + the interactive development of a proof, use the command ``Guarded`` + (see Section :ref:`requestinginformation`). + +.. tacv:: cofix @ident with {+ (@ident {+ @binder} : @type)} + + This starts a proof by mutual coinduction. The statements to be + simultaneously proved are respectively :g:`forall binder ... binder, type` + The identifiers :n:`@ident` are the names of the coinduction hypotheses. + +.. _rewritingexpressions: + +Rewriting expressions +--------------------- + +These tactics use the equality :g:`eq:forall A:Type, A->A->Prop` defined in +file ``Logic.v`` (see :ref:`coq-library-logic`). The notation for :g:`eq T t u` is +simply :g:`t=u` dropping the implicit type of :g:`t` and :g:`u`. + +.. tacn:: rewrite @term + :name: rewrite + + This tactic applies to any goal. The type of :token:`term` must have the form + + ``forall (x``:sub:`1` ``:A``:sub:`1` ``) ... (x``:sub:`n` ``:A``:sub:`n` ``). eq term``:sub:`1` ``term``:sub:`2` ``.`` + + where :g:`eq` is the Leibniz equality or a registered setoid equality. + + Then :n:`rewrite @term` finds the first subterm matching `term`\ :sub:`1` in the goal, + resulting in instances `term`:sub:`1`' and `term`:sub:`2`' and then + replaces every occurrence of `term`:subscript:`1`' by `term`:subscript:`2`'. + Hence, some of the variables :g:`x`\ :sub:`i` are solved by unification, + and some of the types :g:`A`\ :sub:`1`:g:`, ..., A`\ :sub:`n` become new + subgoals. + + .. exn:: The @term provided does not end with an equation. + :undocumented: + + .. exn:: Tactic generated a subgoal identical to the original goal. This happens if @term does not occur in the goal. + :undocumented: + + .. tacv:: rewrite -> @term + + Is equivalent to :n:`rewrite @term` + + .. tacv:: rewrite <- @term + + Uses the equality :n:`@term`:sub:`1` :n:`= @term` :sub:`2` from right to left + + .. tacv:: rewrite @term in clause + + Analogous to :n:`rewrite @term` but rewriting is done following clause + (similarly to :ref:`performing computations <performingcomputations>`). For instance: + + + :n:`rewrite H in H`:sub:`1` will rewrite `H` in the hypothesis + `H`:sub:`1` instead of the current goal. + + :n:`rewrite H in H`:sub:`1` :g:`at 1, H`:sub:`2` :g:`at - 2 |- *` means + :n:`rewrite H; rewrite H in H`:sub:`1` :g:`at 1; rewrite H in H`:sub:`2` :g:`at - 2.` + In particular a failure will happen if any of these three simpler tactics + fails. + + :n:`rewrite H in * |-` will do :n:`rewrite H in H`:sub:`i` for all hypotheses + :g:`H`:sub:`i` different from :g:`H`. + A success will happen as soon as at least one of these simpler tactics succeeds. + + :n:`rewrite H in *` is a combination of :n:`rewrite H` and :n:`rewrite H in * |-` + that succeeds if at least one of these two tactics succeeds. + + Orientation :g:`->` or :g:`<-` can be inserted before the :token:`term` to rewrite. + + .. tacv:: rewrite @term at occurrences + + Rewrite only the given occurrences of :token:`term`. Occurrences are + specified from left to right as for pattern (:tacn:`pattern`). The rewrite is + always performed using setoid rewriting, even for Leibniz’s equality, so one + has to ``Import Setoid`` to use this variant. + + .. tacv:: rewrite @term by tactic + + Use tactic to completely solve the side-conditions arising from the + :tacn:`rewrite`. + + .. tacv:: rewrite {+, @term} + + Is equivalent to the `n` successive tactics :n:`{+; rewrite @term}`, each one + working on the first subgoal generated by the previous one. Orientation + :g:`->` or :g:`<-` can be inserted before each :token:`term` to rewrite. One + unique clause can be added at the end after the keyword in; it will then + affect all rewrite operations. + + In all forms of rewrite described above, a :token:`term` to rewrite can be + immediately prefixed by one of the following modifiers: + + + `?` : the tactic :n:`rewrite ?@term` performs the rewrite of :token:`term` as many + times as possible (perhaps zero time). This form never fails. + + :n:`@num?` : works similarly, except that it will do at most :token:`num` rewrites. + + `!` : works as `?`, except that at least one rewrite should succeed, otherwise + the tactic fails. + + :n:`@num!` (or simply :n:`@num`) : precisely :token:`num` rewrites of :token:`term` will be done, + leading to failure if these :token:`num` rewrites are not possible. + + .. tacv:: erewrite @term + :name: erewrite + + This tactic works as :n:`rewrite @term` but turning + unresolved bindings into existential variables, if any, instead of + failing. It has the same variants as :tacn:`rewrite` has. + + .. flag:: Keyed Unification + + Makes higher-order unification used by :tacn:`rewrite` rely on a set of keys to drive + unification. The subterms, considered as rewriting candidates, must start with + the same key as the left- or right-hand side of the lemma given to rewrite, and the arguments + are then unified up to full reduction. + +.. tacn:: replace @term with @term’ + :name: replace + + This tactic applies to any goal. It replaces all free occurrences of :n:`@term` + in the current goal with :n:`@term’` and generates an equality :n:`@term = @term’` + as a subgoal. This equality is automatically solved if it occurs among + the assumptions, or if its symmetric form occurs. It is equivalent to + :n:`cut @term = @term’; [intro H`:sub:`n` :n:`; rewrite <- H`:sub:`n` :n:`; clear H`:sub:`n`:n:`|| assumption || symmetry; try assumption]`. + + .. exn:: Terms do not have convertible types. + :undocumented: + + .. tacv:: replace @term with @term’ by @tactic + + This acts as :n:`replace @term with @term’` but applies :token:`tactic` to solve the generated + subgoal :n:`@term = @term’`. + + .. tacv:: replace @term + + Replaces :n:`@term` with :n:`@term’` using the first assumption whose type has + the form :n:`@term = @term’` or :n:`@term’ = @term`. + + .. tacv:: replace -> @term + + Replaces :n:`@term` with :n:`@term’` using the first assumption whose type has + the form :n:`@term = @term’` + + .. tacv:: replace <- @term + + Replaces :n:`@term` with :n:`@term’` using the first assumption whose type has + the form :n:`@term’ = @term` + + .. tacv:: replace @term {? with @term} in clause {? by @tactic} + replace -> @term in clause + replace <- @term in clause + + Acts as before but the replacements take place in the specified clause (see + :ref:`performingcomputations`) and not only in the conclusion of the goal. The + clause argument must not contain any ``type of`` nor ``value of``. + + .. tacv:: cutrewrite <- (@term = @term’) + :name: cutrewrite + + This tactic is deprecated. It can be replaced by :n:`enough (@term = @term’) as <-`. + + .. tacv:: cutrewrite -> (@term = @term’) + + This tactic is deprecated. It can be replaced by :n:`enough (@term = @term’) as ->`. + + +.. tacn:: subst @ident + :name: subst + + This tactic applies to a goal that has :n:`@ident` in its context and (at + least) one hypothesis, say :g:`H`, of type :n:`@ident = t` or :n:`t = @ident` + with :n:`@ident` not occurring in :g:`t`. Then it replaces :n:`@ident` by + :g:`t` everywhere in the goal (in the hypotheses and in the conclusion) and + clears :n:`@ident` and :g:`H` from the context. + + If :n:`@ident` is a local definition of the form :n:`@ident := t`, it is also + unfolded and cleared. + + .. note:: + + When several hypotheses have the form :n:`@ident = t` or :n:`t = @ident`, the + first one is used. + + + If :g:`H` is itself dependent in the goal, it is replaced by the proof of + reflexivity of equality. + + .. tacv:: subst {+ @ident} + + This is equivalent to :n:`subst @ident`:sub:`1`:n:`; ...; subst @ident`:sub:`n`. + + .. tacv:: subst + + This applies subst repeatedly from top to bottom to all identifiers of the + context for which an equality of the form :n:`@ident = t` or :n:`t = @ident` + or :n:`@ident := t` exists, with :n:`@ident` not occurring in ``t``. + + .. flag:: Regular Subst Tactic + + This option controls the behavior of :tacn:`subst`. When it is + activated (it is by default), :tacn:`subst` also deals with the following corner cases: + + + A context with ordered hypotheses :n:`@ident`:sub:`1` :n:`= @ident`:sub:`2` + and :n:`@ident`:sub:`1` :n:`= t`, or :n:`t′ = @ident`:sub:`1`` with `t′` not + a variable, and no other hypotheses of the form :n:`@ident`:sub:`2` :n:`= u` + or :n:`u = @ident`:sub:`2`; without the option, a second call to + subst would be necessary to replace :n:`@ident`:sub:`2` by `t` or + `t′` respectively. + + The presence of a recursive equation which without the option would + be a cause of failure of :tacn:`subst`. + + A context with cyclic dependencies as with hypotheses :n:`@ident`:sub:`1` :n:`= f @ident`:sub:`2` + and :n:`@ident`:sub:`2` :n:`= g @ident`:sub:`1` which without the + option would be a cause of failure of :tacn:`subst`. + + Additionally, it prevents a local definition such as :n:`@ident := t` to be + unfolded which otherwise it would exceptionally unfold in configurations + containing hypotheses of the form :n:`@ident = u`, or :n:`u′ = @ident` + with `u′` not a variable. Finally, it preserves the initial order of + hypotheses, which without the option it may break. + default. + + +.. tacn:: stepl @term + :name: stepl + + This tactic is for chaining rewriting steps. It assumes a goal of the + form :n:`R @term @term` where ``R`` is a binary relation and relies on a + database of lemmas of the form :g:`forall x y z, R x y -> eq x z -> R z y` + where `eq` is typically a setoid equality. The application of :n:`stepl @term` + then replaces the goal by :n:`R @term @term` and adds a new goal stating + :n:`eq @term @term`. + + .. cmd:: Declare Left Step @term + + Adds :n:`@term` to the database used by :tacn:`stepl`. + + This tactic is especially useful for parametric setoids which are not accepted + as regular setoids for :tacn:`rewrite` and :tacn:`setoid_replace` (see + :ref:`Generalizedrewriting`). + + .. tacv:: stepl @term by @tactic + + This applies :n:`stepl @term` then applies :token:`tactic` to the second goal. + + .. tacv:: stepr @term stepr @term by tactic + :name: stepr + + This behaves as :tacn:`stepl` but on the right-hand-side of the binary + relation. Lemmas are expected to be of the form + :g:`forall x y z, R x y -> eq y z -> R x z`. + + .. cmd:: Declare Right Step @term + + Adds :n:`@term` to the database used by :tacn:`stepr`. + + +.. tacn:: change @term + :name: change + + This tactic applies to any goal. It implements the rule ``Conv`` given in + :ref:`subtyping-rules`. :g:`change U` replaces the current goal `T` + with `U` providing that `U` is well-formed and that `T` and `U` are + convertible. + + .. exn:: Not convertible. + :undocumented: + + .. tacv:: change @term with @term’ + + This replaces the occurrences of :n:`@term` by :n:`@term’` in the current goal. + The term :n:`@term` and :n:`@term’` must be convertible. + + .. tacv:: change @term at {+ @num} with @term’ + + This replaces the occurrences numbered :n:`{+ @num}` of :n:`@term` by :n:`@term’` + in the current goal. The terms :n:`@term` and :n:`@term’` must be convertible. + + .. exn:: Too few occurrences. + :undocumented: + + .. tacv:: change @term {? {? at {+ @num}} with @term} in @ident + + This applies the :tacn:`change` tactic not to the goal but to the hypothesis :n:`@ident`. + + .. tacv:: now_show @term + + This is a synonym of :n:`change @term`. It can be used to + make some proof steps explicit when refactoring a proof script + to make it readable. + + .. seealso:: :ref:`Performing computations <performingcomputations>` + +.. _performingcomputations: + +Performing computations +--------------------------- + +This set of tactics implements different specialized usages of the +tactic :tacn:`change`. + +All conversion tactics (including :tacn:`change`) can be parameterized by the +parts of the goal where the conversion can occur. This is done using +*goal clauses* which consists in a list of hypotheses and, optionally, +of a reference to the conclusion of the goal. For defined hypothesis +it is possible to specify if the conversion should occur on the type +part, the body part or both (default). + +Goal clauses are written after a conversion tactic (tactics :tacn:`set`, +:tacn:`rewrite`, :tacn:`replace` and :tacn:`autorewrite` also use goal +clauses) and are introduced by the keyword `in`. If no goal clause is +provided, the default is to perform the conversion only in the +conclusion. + +The syntax and description of the various goal clauses is the +following: + ++ :n:`in {+ @ident} |-` only in hypotheses :n:`{+ @ident}` ++ :n:`in {+ @ident} |- *` in hypotheses :n:`{+ @ident}` and in the + conclusion ++ :n:`in * |-` in every hypothesis ++ :n:`in *` (equivalent to in :n:`* |- *`) everywhere ++ :n:`in (type of @ident) (value of @ident) ... |-` in type part of + :n:`@ident`, in the value part of :n:`@ident`, etc. + +For backward compatibility, the notation :n:`in {+ @ident}` performs +the conversion in hypotheses :n:`{+ @ident}`. + +.. tacn:: cbv {* @flag} + lazy {* @flag} + :name: cbv; lazy + + These parameterized reduction tactics apply to any goal and perform + the normalization of the goal according to the specified flags. In + correspondence with the kinds of reduction considered in Coq namely + :math:`\beta` (reduction of functional application), :math:`\delta` + (unfolding of transparent constants, see :ref:`vernac-controlling-the-reduction-strategies`), + :math:`\iota` (reduction of + pattern matching over a constructed term, and unfolding of :g:`fix` and + :g:`cofix` expressions) and :math:`\zeta` (contraction of local definitions), the + flags are either ``beta``, ``delta``, ``match``, ``fix``, ``cofix``, + ``iota`` or ``zeta``. The ``iota`` flag is a shorthand for ``match``, ``fix`` + and ``cofix``. The ``delta`` flag itself can be refined into + :n:`delta {+ @qualid}` or :n:`delta -{+ @qualid}`, restricting in the first + case the constants to unfold to the constants listed, and restricting in the + second case the constant to unfold to all but the ones explicitly mentioned. + Notice that the ``delta`` flag does not apply to variables bound by a let-in + construction inside the :n:`@term` itself (use here the ``zeta`` flag). In + any cases, opaque constants are not unfolded (see :ref:`vernac-controlling-the-reduction-strategies`). + + Normalization according to the flags is done by first evaluating the + head of the expression into a *weak-head* normal form, i.e. until the + evaluation is blocked by a variable (or an opaque constant, or an + axiom), as e.g. in :g:`x u1 ... un` , or :g:`match x with ... end`, or + :g:`(fix f x {struct x} := ...) x`, or is a constructed form (a + :math:`\lambda`-expression, a constructor, a cofixpoint, an inductive type, a + product type, a sort), or is a redex that the flags prevent to reduce. Once a + weak-head normal form is obtained, subterms are recursively reduced using the + same strategy. + + Reduction to weak-head normal form can be done using two strategies: + *lazy* (``lazy`` tactic), or *call-by-value* (``cbv`` tactic). The lazy + strategy is a call-by-need strategy, with sharing of reductions: the + arguments of a function call are weakly evaluated only when necessary, + and if an argument is used several times then it is weakly computed + only once. This reduction is efficient for reducing expressions with + dead code. For instance, the proofs of a proposition :g:`exists x. P(x)` + reduce to a pair of a witness :g:`t`, and a proof that :g:`t` satisfies the + predicate :g:`P`. Most of the time, :g:`t` may be computed without computing + the proof of :g:`P(t)`, thanks to the lazy strategy. + + The call-by-value strategy is the one used in ML languages: the + arguments of a function call are systematically weakly evaluated + first. Despite the lazy strategy always performs fewer reductions than + the call-by-value strategy, the latter is generally more efficient for + evaluating purely computational expressions (i.e. with little dead code). + +.. tacv:: compute + cbv + :name: compute; _ + + These are synonyms for ``cbv beta delta iota zeta``. + +.. tacv:: lazy + + This is a synonym for ``lazy beta delta iota zeta``. + +.. tacv:: compute {+ @qualid} + cbv {+ @qualid} + + These are synonyms of :n:`cbv beta delta {+ @qualid} iota zeta`. + +.. tacv:: compute -{+ @qualid} + cbv -{+ @qualid} + + These are synonyms of :n:`cbv beta delta -{+ @qualid} iota zeta`. + +.. tacv:: lazy {+ @qualid} + lazy -{+ @qualid} + + These are respectively synonyms of :n:`lazy beta delta {+ @qualid} iota zeta` + and :n:`lazy beta delta -{+ @qualid} iota zeta`. + +.. tacv:: vm_compute + :name: vm_compute + + This tactic evaluates the goal using the optimized call-by-value evaluation + bytecode-based virtual machine described in :cite:`CompiledStrongReduction`. + This algorithm is dramatically more efficient than the algorithm used for the + ``cbv`` tactic, but it cannot be fine-tuned. It is specially interesting for + full evaluation of algebraic objects. This includes the case of + reflection-based tactics. + +.. tacv:: native_compute + :name: native_compute + + This tactic evaluates the goal by compilation to Objective Caml as described + in :cite:`FullReduction`. If Coq is running in native code, it can be + typically two to five times faster than ``vm_compute``. Note however that the + compilation cost is higher, so it is worth using only for intensive + computations. + + .. flag:: NativeCompute Profiling + + On Linux, if you have the ``perf`` profiler installed, this option makes + it possible to profile ``native_compute`` evaluations. + + .. opt:: NativeCompute Profile Filename @string + :name: NativeCompute Profile Filename + + This option specifies the profile output; the default is + ``native_compute_profile.data``. The actual filename used + will contain extra characters to avoid overwriting an existing file; that + filename is reported to the user. + That means you can individually profile multiple uses of + ``native_compute`` in a script. From the Linux command line, run ``perf report`` + on the profile file to see the results. Consult the ``perf`` documentation + for more details. + +.. flag:: Debug Cbv + + This option makes :tacn:`cbv` (and its derivative :tacn:`compute`) print + information about the constants it encounters and the unfolding decisions it + makes. + +.. tacn:: red + :name: red + + This tactic applies to a goal that has the form:: + + forall (x:T1) ... (xk:Tk), T + + with :g:`T` :math:`\beta`:math:`\iota`:math:`\zeta`-reducing to :g:`c t`:sub:`1` :g:`... t`:sub:`n` and :g:`c` a + constant. If :g:`c` is transparent then it replaces :g:`c` with its + definition (say :g:`t`) and then reduces + :g:`(t t`:sub:`1` :g:`... t`:sub:`n` :g:`)` according to :math:`\beta`:math:`\iota`:math:`\zeta`-reduction rules. + +.. exn:: Not reducible. + :undocumented: + +.. exn:: No head constant to reduce. + :undocumented: + +.. tacn:: hnf + :name: hnf + + This tactic applies to any goal. It replaces the current goal with its + head normal form according to the :math:`\beta`:math:`\delta`:math:`\iota`:math:`\zeta`-reduction rules, i.e. it + reduces the head of the goal until it becomes a product or an + irreducible term. All inner :math:`\beta`:math:`\iota`-redexes are also reduced. + + Example: The term :g:`fun n : nat => S n + S n` is not reduced by :n:`hnf`. + +.. note:: + The :math:`\delta` rule only applies to transparent constants (see :ref:`vernac-controlling-the-reduction-strategies` + on transparency and opacity). + +.. tacn:: cbn + simpl + :name: cbn; simpl + + These tactics apply to any goal. They try to reduce a term to + something still readable instead of fully normalizing it. They perform + a sort of strong normalization with two key differences: + + + They unfold a constant if and only if it leads to a :math:`\iota`-reduction, + i.e. reducing a match or unfolding a fixpoint. + + While reducing a constant unfolding to (co)fixpoints, the tactics + use the name of the constant the (co)fixpoint comes from instead of + the (co)fixpoint definition in recursive calls. + + The ``cbn`` tactic is claimed to be a more principled, faster and more + predictable replacement for ``simpl``. + + The ``cbn`` tactic accepts the same flags as ``cbv`` and ``lazy``. The + behavior of both ``simpl`` and ``cbn`` can be tuned using the + Arguments vernacular command as follows: + + + A constant can be marked to be never unfolded by ``cbn`` or ``simpl``: + + .. example:: + + .. coqtop:: all + + Arguments minus n m : simpl never. + + After that command an expression like :g:`(minus (S x) y)` is left + untouched by the tactics ``cbn`` and ``simpl``. + + + A constant can be marked to be unfolded only if applied to enough + arguments. The number of arguments required can be specified using the + ``/`` symbol in the argument list of the :cmd:`Arguments` vernacular command. + + .. example:: + + .. coqtop:: all + + Definition fcomp A B C f (g : A -> B) (x : A) : C := f (g x). + Arguments fcomp {A B C} f g x /. + Notation "f \o g" := (fcomp f g) (at level 50). + + After that command the expression :g:`(f \o g)` is left untouched by + ``simpl`` while :g:`((f \o g) t)` is reduced to :g:`(f (g t))`. + The same mechanism can be used to make a constant volatile, i.e. + always unfolded. + + .. example:: + + .. coqtop:: all + + Definition volatile := fun x : nat => x. + Arguments volatile / x. + + + A constant can be marked to be unfolded only if an entire set of + arguments evaluates to a constructor. The ``!`` symbol can be used to mark + such arguments. + + .. example:: + + .. coqtop:: all + + Arguments minus !n !m. + + After that command, the expression :g:`(minus (S x) y)` is left untouched + by ``simpl``, while :g:`(minus (S x) (S y))` is reduced to :g:`(minus x y)`. + + + A special heuristic to determine if a constant has to be unfolded + can be activated with the following command: + + .. example:: + + .. coqtop:: all + + Arguments minus n m : simpl nomatch. + + The heuristic avoids to perform a simplification step that would expose a + match construct in head position. For example the expression + :g:`(minus (S (S x)) (S y))` is simplified to :g:`(minus (S x) y)` + even if an extra simplification is possible. + + In detail, the tactic ``simpl`` first applies :math:`\beta`:math:`\iota`-reduction. Then, it + expands transparent constants and tries to reduce further using :math:`\beta`:math:`\iota`- + reduction. But, when no :math:`\iota` rule is applied after unfolding then + :math:`\delta`-reductions are not applied. For instance trying to use ``simpl`` on + :g:`(plus n O) = n` changes nothing. + + Notice that only transparent constants whose name can be reused in the + recursive calls are possibly unfolded by ``simpl``. For instance a + constant defined by :g:`plus' := plus` is possibly unfolded and reused in + the recursive calls, but a constant such as :g:`succ := plus (S O)` is + never unfolded. This is the main difference between ``simpl`` and ``cbn``. + The tactic ``cbn`` reduces whenever it will be able to reuse it or not: + :g:`succ t` is reduced to :g:`S t`. + +.. tacv:: cbn {+ @qualid} + cbn -{+ @qualid} + + These are respectively synonyms of :n:`cbn beta delta {+ @qualid} iota zeta` + and :n:`cbn beta delta -{+ @qualid} iota zeta` (see :tacn:`cbn`). + +.. tacv:: simpl @pattern + + This applies ``simpl`` only to the subterms matching :n:`@pattern` in the + current goal. + +.. tacv:: simpl @pattern at {+ @num} + + This applies ``simpl`` only to the :n:`{+ @num}` occurrences of the subterms + matching :n:`@pattern` in the current goal. + + .. exn:: Too few occurrences. + :undocumented: + +.. tacv:: simpl @qualid + simpl @string + + This applies :tacn:`simpl` only to the applicative subterms whose head occurrence + is the unfoldable constant :n:`@qualid` (the constant can be referred to by + its notation using :n:`@string` if such a notation exists). + +.. tacv:: simpl @qualid at {+ @num} + simpl @string at {+ @num} + + This applies ``simpl`` only to the :n:`{+ @num}` applicative subterms whose + head occurrence is :n:`@qualid` (or :n:`@string`). + +.. flag:: Debug RAKAM + + This option makes :tacn:`cbn` print various debugging information. + ``RAKAM`` is the Refolding Algebraic Krivine Abstract Machine. + +.. tacn:: unfold @qualid + :name: unfold + + This tactic applies to any goal. The argument qualid must denote a + defined transparent constant or local definition (see + :ref:`gallina-definitions` and :ref:`vernac-controlling-the-reduction-strategies`). The tactic + ``unfold`` applies the :math:`\delta` rule to each occurrence of the constant to which + :n:`@qualid` refers in the current goal and then replaces it with its + :math:`\beta`:math:`\iota`-normal form. + +.. exn:: @qualid does not denote an evaluable constant. + :undocumented: + +.. tacv:: unfold @qualid in @ident + + Replaces :n:`@qualid` in hypothesis :n:`@ident` with its definition + and replaces the hypothesis with its :math:`\beta`:math:`\iota` normal form. + +.. tacv:: unfold {+, @qualid} + + Replaces *simultaneously* :n:`{+, @qualid}` with their definitions and + replaces the current goal with its :math:`\beta`:math:`\iota` normal form. + +.. tacv:: unfold {+, @qualid at {+, @num }} + + The lists :n:`{+, @num}` specify the occurrences of :n:`@qualid` to be + unfolded. Occurrences are located from left to right. + + .. exn:: Bad occurrence number of @qualid. + :undocumented: + + .. exn:: @qualid does not occur. + :undocumented: + +.. tacv:: unfold @string + + If :n:`@string` denotes the discriminating symbol of a notation (e.g. "+") or + an expression defining a notation (e.g. `"_ + _"`), and this notation refers to an unfoldable constant, then the + tactic unfolds it. + +.. tacv:: unfold @string%key + + This is variant of :n:`unfold @string` where :n:`@string` gets its + interpretation from the scope bound to the delimiting key :n:`key` + instead of its default interpretation (see :ref:`Localinterpretationrulesfornotations`). +.. tacv:: unfold {+, qualid_or_string at {+, @num}} + + This is the most general form, where :n:`qualid_or_string` is either a + :n:`@qualid` or a :n:`@string` referring to a notation. + +.. tacn:: fold @term + :name: fold + + This tactic applies to any goal. The term :n:`@term` is reduced using the + :tacn:`red` tactic. Every occurrence of the resulting :n:`@term` in the goal is + then replaced by :n:`@term`. This tactic is particularly useful when a fixpoint + definition has been wrongfully unfolded, making the goal very hard to read. + On the other hand, when an unfolded function applied to its argument has been + reduced, the :tacn:`fold` tactic won't do anything. + + .. example:: + + .. coqtop:: all abort + + Goal ~0=0. + unfold not. + Fail progress fold not. + pattern (0 = 0). + fold not. + + .. tacv:: fold {+ @term} + + Equivalent to :n:`fold @term ; ... ; fold @term`. + +.. tacn:: pattern @term + :name: pattern + + This command applies to any goal. The argument :n:`@term` must be a free + subterm of the current goal. The command pattern performs :math:`\beta`-expansion + (the inverse of :math:`\beta`-reduction) of the current goal (say :g:`T`) by + + + replacing all occurrences of :n:`@term` in :g:`T` with a fresh variable + + abstracting this variable + + applying the abstracted goal to :n:`@term` + + For instance, if the current goal :g:`T` is expressible as + :math:`\varphi`:g:`(t)` where the notation captures all the instances of :g:`t` + in :math:`\varphi`:g:`(t)`, then :n:`pattern t` transforms it into + :g:`(fun x:A =>` :math:`\varphi`:g:`(x)) t`. This tactic can be used, for + instance, when the tactic ``apply`` fails on matching. + +.. tacv:: pattern @term at {+ @num} + + Only the occurrences :n:`{+ @num}` of :n:`@term` are considered for + :math:`\beta`-expansion. Occurrences are located from left to right. + +.. tacv:: pattern @term at - {+ @num} + + All occurrences except the occurrences of indexes :n:`{+ @num }` + of :n:`@term` are considered for :math:`\beta`-expansion. Occurrences are located from + left to right. + +.. tacv:: pattern {+, @term} + + Starting from a goal :math:`\varphi`:g:`(t`:sub:`1` :g:`... t`:sub:`m`:g:`)`, + the tactic :n:`pattern t`:sub:`1`:n:`, ..., t`:sub:`m` generates the + equivalent goal + :g:`(fun (x`:sub:`1`:g:`:A`:sub:`1`:g:`) ... (x`:sub:`m` :g:`:A`:sub:`m` :g:`) =>`:math:`\varphi`:g:`(x`:sub:`1` :g:`... x`:sub:`m` :g:`)) t`:sub:`1` :g:`... t`:sub:`m`. + If :g:`t`:sub:`i` occurs in one of the generated types :g:`A`:sub:`j` these + occurrences will also be considered and possibly abstracted. + +.. tacv:: pattern {+, @term at {+ @num}} + + This behaves as above but processing only the occurrences :n:`{+ @num}` of + :n:`@term` starting from :n:`@term`. + +.. tacv:: pattern {+, @term {? at {? -} {+, @num}}} + + This is the most general syntax that combines the different variants. + +Conversion tactics applied to hypotheses +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. tacn:: conv_tactic in {+, @ident} + + Applies the conversion tactic :n:`conv_tactic` to the hypotheses + :n:`{+ @ident}`. The tactic :n:`conv_tactic` is any of the conversion tactics + listed in this section. + + If :n:`@ident` is a local definition, then :n:`@ident` can be replaced by + (type of :n:`@ident`) to address not the body but the type of the local + definition. + + Example: :n:`unfold not in (type of H1) (type of H3)`. + +.. exn:: No such hypothesis: @ident. + :undocumented: + + +.. _automation: + +Automation +---------- + +.. tacn:: auto + :name: auto + + This tactic implements a Prolog-like resolution procedure to solve the + current goal. It first tries to solve the goal using the :tacn:`assumption` + tactic, then it reduces the goal to an atomic one using :tacn:`intros` and + introduces the newly generated hypotheses as hints. Then it looks at + the list of tactics associated to the head symbol of the goal and + tries to apply one of them (starting from the tactics with lower + cost). This process is recursively applied to the generated subgoals. + + By default, :tacn:`auto` only uses the hypotheses of the current goal and + the hints of the database named ``core``. + + .. warning:: + + :tacn:`auto` uses a weaker version of :tacn:`apply` that is closer to + :tacn:`simple apply` so it is expected that sometimes :tacn:`auto` will + fail even if applying manually one of the hints would succeed. + + .. tacv:: auto @num + + Forces the search depth to be :token:`num`. The maximal search depth + is 5 by default. + + .. tacv:: auto with {+ @ident} + + Uses the hint databases :n:`{+ @ident}` in addition to the database ``core``. + + .. note:: + + Use the fake database `nocore` if you want to *not* use the `core` + database. + + .. tacv:: auto with * + + Uses all existing hint databases. Using this variant is highly discouraged + in finished scripts since it is both slower and less robust than the variant + where the required databases are explicitly listed. + + .. seealso:: + :ref:`The Hints Databases for auto and eauto <thehintsdatabasesforautoandeauto>` for the list of + pre-defined databases and the way to create or extend a database. + + .. tacv:: auto using {+ @ident__i} {? with {+ @ident } } + + Uses lemmas :n:`@ident__i` in addition to hints. If :n:`@ident` is an + inductive type, it is the collection of its constructors which are added + as hints. + + .. note:: + + The hints passed through the `using` clause are used in the same + way as if they were passed through a hint database. Consequently, + they use a weaker version of :tacn:`apply` and :n:`auto using @ident` + may fail where :n:`apply @ident` succeeds. + + Given that this can be seen as counter-intuitive, it could be useful + to have an option to use full-blown :tacn:`apply` for lemmas passed + through the `using` clause. Contributions welcome! + + .. tacv:: info_auto + + Behaves like :tacn:`auto` but shows the tactics it uses to solve the goal. This + variant is very useful for getting a better understanding of automation, or + to know what lemmas/assumptions were used. + + .. tacv:: debug auto + :name: debug auto + + Behaves like :tacn:`auto` but shows the tactics it tries to solve the goal, + including failing paths. + + .. tacv:: {? info_}auto {? @num} {? using {+ @lemma}} {? with {+ @ident}} + + This is the most general form, combining the various options. + +.. tacv:: trivial + :name: trivial + + This tactic is a restriction of :tacn:`auto` that is not recursive + and tries only hints that cost `0`. Typically it solves trivial + equalities like :g:`X=X`. + + .. tacv:: trivial with {+ @ident} + trivial with * + trivial using {+ @lemma} + debug trivial + info_trivial + {? info_}trivial {? using {+ @lemma}} {? with {+ @ident}} + :name: _; _; _; debug trivial; info_trivial; _ + :undocumented: + +.. note:: + :tacn:`auto` and :tacn:`trivial` either solve completely the goal or + else succeed without changing the goal. Use :g:`solve [ auto ]` and + :g:`solve [ trivial ]` if you would prefer these tactics to fail when + they do not manage to solve the goal. + +.. flag:: Info Auto + Debug Auto + Info Trivial + Debug Trivial + + These options enable printing of informative or debug information for + the :tacn:`auto` and :tacn:`trivial` tactics. + +.. tacn:: eauto + :name: eauto + + This tactic generalizes :tacn:`auto`. While :tacn:`auto` does not try + resolution hints which would leave existential variables in the goal, + :tacn:`eauto` does try them (informally speaking, it internally uses a tactic + close to :tacn:`simple eapply` instead of a tactic close to :tacn:`simple apply` + in the case of :tacn:`auto`). As a consequence, :tacn:`eauto` + can solve such a goal: + + .. example:: + + .. coqtop:: all + + Hint Resolve ex_intro : core. + Goal forall P:nat -> Prop, P 0 -> exists n, P n. + eauto. + + Note that ``ex_intro`` should be declared as a hint. + + + .. tacv:: {? info_}eauto {? @num} {? using {+ @lemma}} {? with {+ @ident}} + + The various options for :tacn:`eauto` are the same as for :tacn:`auto`. + + :tacn:`eauto` also obeys the following options: + + .. flag:: Info Eauto + Debug Eauto + :undocumented: + + .. seealso:: :ref:`The Hints Databases for auto and eauto <thehintsdatabasesforautoandeauto>` + + +.. tacn:: autounfold with {+ @ident} + :name: autounfold + + This tactic unfolds constants that were declared through a :cmd:`Hint Unfold` + in the given databases. + +.. tacv:: autounfold with {+ @ident} in clause + + Performs the unfolding in the given clause. + +.. tacv:: autounfold with * + + Uses the unfold hints declared in all the hint databases. + +.. tacn:: autorewrite with {+ @ident} + :name: autorewrite + + This tactic [4]_ carries out rewritings according to the rewriting rule + bases :n:`{+ @ident}`. + + Each rewriting rule from the base :n:`@ident` is applied to the main subgoal until + it fails. Once all the rules have been processed, if the main subgoal has + progressed (e.g., if it is distinct from the initial main goal) then the rules + of this base are processed again. If the main subgoal has not progressed then + the next base is processed. For the bases, the behavior is exactly similar to + the processing of the rewriting rules. + + The rewriting rule bases are built with the :cmd:`Hint Rewrite` + command. + +.. warning:: + + This tactic may loop if you build non terminating rewriting systems. + +.. tacv:: autorewrite with {+ @ident} using @tactic + + Performs, in the same way, all the rewritings of the bases :n:`{+ @ident}` + applying tactic to the main subgoal after each rewriting step. + +.. tacv:: autorewrite with {+ @ident} in @qualid + + Performs all the rewritings in hypothesis :n:`@qualid`. + +.. tacv:: autorewrite with {+ @ident} in @qualid using @tactic + + Performs all the rewritings in hypothesis :n:`@qualid` applying :n:`@tactic` + to the main subgoal after each rewriting step. + +.. tacv:: autorewrite with {+ @ident} in @clause + + Performs all the rewriting in the clause :n:`@clause`. The clause argument + must not contain any ``type of`` nor ``value of``. + +.. seealso:: + + :ref:`Hint-Rewrite <hintrewrite>` for feeding the database of lemmas used by + :tacn:`autorewrite` and :tacn:`autorewrite` for examples showing the use of this tactic. + +.. tacn:: easy + :name: easy + + This tactic tries to solve the current goal by a number of standard closing steps. + In particular, it tries to close the current goal using the closing tactics + :tacn:`trivial`, :tacn:`reflexivity`, :tacn:`symmetry`, :tacn:`contradiction` + and :tacn:`inversion` of hypothesis. + If this fails, it tries introducing variables and splitting and-hypotheses, + using the closing tactics afterwards, and splitting the goal using + :tacn:`split` and recursing. + + This tactic solves goals that belong to many common classes; in particular, many cases of + unsatisfiable hypotheses, and simple equality goals are usually solved by this tactic. + +.. tacv:: now @tactic + :name: now + + Run :n:`@tactic` followed by :tacn:`easy`. This is a notation for :n:`@tactic; easy`. + +Controlling automation +-------------------------- + +.. _thehintsdatabasesforautoandeauto: + +The hints databases for auto and eauto +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +The hints for :tacn:`auto` and :tacn:`eauto` are stored in databases. Each database +maps head symbols to a list of hints. + +.. cmd:: Print Hint @ident + + Use this command + to display the hints associated to the head symbol :n:`@ident` + (see :ref:`Print Hint <printhint>`). Each hint has a cost that is a nonnegative + integer, and an optional pattern. The hints with lower cost are tried first. A + hint is tried by :tacn:`auto` when the conclusion of the current goal matches its + pattern or when it has no pattern. + +Creating Hint databases +``````````````````````` + +One can optionally declare a hint database using the command +:cmd:`Create HintDb`. If a hint is added to an unknown database, it will be +automatically created. + +.. cmd:: Create HintDb @ident {? discriminated} + + This command creates a new database named :n:`@ident`. The database is + implemented by a Discrimination Tree (DT) that serves as an index of + all the lemmas. The DT can use transparency information to decide if a + constant should be indexed or not + (c.f. :ref:`The hints databases for auto and eauto <thehintsdatabasesforautoandeauto>`), + making the retrieval more efficient. The legacy implementation (the default one + for new databases) uses the DT only on goals without existentials (i.e., :tacn:`auto` + goals), for non-Immediate hints and does not make use of transparency + hints, putting more work on the unification that is run after + retrieval (it keeps a list of the lemmas in case the DT is not used). + The new implementation enabled by the discriminated option makes use + of DTs in all cases and takes transparency information into account. + However, the order in which hints are retrieved from the DT may differ + from the order in which they were inserted, making this implementation + observationally different from the legacy one. + +The general command to add a hint to some databases :n:`{+ @ident}` is + +.. cmd:: Hint @hint_definition : {+ @ident} + + .. cmdv:: Hint @hint_definition + + No database name is given: the hint is registered in the ``core`` database. + + .. deprecated:: 8.10 + + .. cmdv:: Local Hint @hint_definition : {+ @ident} + + This is used to declare hints that must not be exported to the other modules + that require and import the current module. Inside a section, the option + Local is useless since hints do not survive anyway to the closure of + sections. + + .. cmdv:: Hint Resolve @term {? | {? @num} {? @pattern}} : @ident + :name: Hint Resolve + + This command adds :n:`simple apply @term` to the hint list with the head + symbol of the type of :n:`@term`. The cost of that hint is the number of + subgoals generated by :n:`simple apply @term` or :n:`@num` if specified. The + associated :n:`@pattern` is inferred from the conclusion of the type of + :n:`@term` or the given :n:`@pattern` if specified. In case the inferred type + of :n:`@term` does not start with a product the tactic added in the hint list + is :n:`exact @term`. In case this type can however be reduced to a type + starting with a product, the tactic :n:`simple apply @term` is also stored in + the hints list. If the inferred type of :n:`@term` contains a dependent + quantification on a variable which occurs only in the premisses of the type + and not in its conclusion, no instance could be inferred for the variable by + unification with the goal. In this case, the hint is added to the hint list + of :tacn:`eauto` instead of the hint list of auto and a warning is printed. A + typical example of a hint that is used only by :tacn:`eauto` is a transitivity + lemma. + + .. exn:: @term cannot be used as a hint + + The head symbol of the type of :n:`@term` is a bound variable + such that this tactic cannot be associated to a constant. + + .. cmdv:: Hint Resolve {+ @term} : @ident + + Adds each :n:`Hint Resolve @term`. + + .. cmdv:: Hint Resolve -> @term : @ident + + Adds the left-to-right implication of an equivalence as a hint (informally + the hint will be used as :n:`apply <- @term`, although as mentionned + before, the tactic actually used is a restricted version of + :tacn:`apply`). + + .. cmdv:: Resolve <- @term + + Adds the right-to-left implication of an equivalence as a hint. + + .. cmdv:: Hint Immediate @term : @ident + :name: Hint Immediate + + This command adds :n:`simple apply @term; trivial` to the hint list associated + with the head symbol of the type of :n:`@ident` in the given database. This + tactic will fail if all the subgoals generated by :n:`simple apply @term` are + not solved immediately by the :tacn:`trivial` tactic (which only tries tactics + with cost 0).This command is useful for theorems such as the symmetry of + equality or :g:`n+1=m+1 -> n=m` that we may like to introduce with a limited + use in order to avoid useless proof-search. The cost of this tactic (which + never generates subgoals) is always 1, so that it is not used by :tacn:`trivial` + itself. + + .. exn:: @term cannot be used as a hint + :undocumented: + + .. cmdv:: Immediate {+ @term} : @ident + + Adds each :n:`Hint Immediate @term`. + + .. cmdv:: Hint Constructors @qualid : @ident + :name: Hint Constructors + + If :token:`qualid` is an inductive type, this command adds all its constructors as + hints of type ``Resolve``. Then, when the conclusion of current goal has the form + :n:`(@qualid ...)`, :tacn:`auto` will try to apply each constructor. + + .. exn:: @qualid is not an inductive type + :undocumented: + + .. cmdv:: Hint Constructors {+ @qualid} : @ident + + Extends the previous command for several inductive types. + + .. cmdv:: Hint Unfold @qualid : @ident + :name: Hint Unfold + + This adds the tactic :n:`unfold @qualid` to the hint list that will only be + used when the head constant of the goal is :token:`qualid`. + Its cost is 4. + + .. cmdv:: Hint Unfold {+ @qualid} + + Extends the previous command for several defined constants. + + .. cmdv:: Hint Transparent {+ @qualid} : @ident + Hint Opaque {+ @qualid} : @ident + :name: Hint Transparent; Hint Opaque + + This adds transparency hints to the database, making :n:`@qualid` + transparent or opaque constants during resolution. This information is used + during unification of the goal with any lemma in the database and inside the + discrimination network to relax or constrain it in the case of discriminated + databases. + + .. cmdv:: Hint Variables %( Transparent %| Opaque %) : @ident + Hint Constants %( Transparent %| Opaque %) : @ident + :name: Hint Variables; Hint Constants + + This sets the transparency flag used during unification of + hints in the database for all constants or all variables, + overwritting the existing settings of opacity. It is advised + to use this just after a :cmd:`Create HintDb` command. + + .. cmdv:: Hint Extern @num {? @pattern} => @tactic : @ident + :name: Hint Extern + + This hint type is to extend :tacn:`auto` with tactics other than :tacn:`apply` and + :tacn:`unfold`. For that, we must specify a cost, an optional :n:`@pattern` and a + :n:`@tactic` to execute. + + .. example:: + + .. coqtop:: in + + Hint Extern 4 (~(_ = _)) => discriminate : core. + + Now, when the head of the goal is a disequality, ``auto`` will try + discriminate if it does not manage to solve the goal with hints with a + cost less than 4. + + One can even use some sub-patterns of the pattern in + the tactic script. A sub-pattern is a question mark followed by an + identifier, like ``?X1`` or ``?X2``. Here is an example: + + .. example:: + + .. coqtop:: reset all + + Require Import List. + Hint Extern 5 ({?X1 = ?X2} + {?X1 <> ?X2}) => generalize X1, X2; decide equality : eqdec. + Goal forall a b:list (nat * nat), {a = b} + {a <> b}. + Info 1 auto with eqdec. + + .. cmdv:: Hint Cut @regexp : @ident + :name: Hint Cut + + .. warning:: + + These hints currently only apply to typeclass proof search and the + :tacn:`typeclasses eauto` tactic. + + This command can be used to cut the proof-search tree according to a regular + expression matching paths to be cut. The grammar for regular expressions is + the following. Beware, there is no operator precedence during parsing, one can + check with :cmd:`Print HintDb` to verify the current cut expression: + + .. productionlist:: regexp + e : `ident` hint or instance identifier + : _ any hint + : `e` | `e` disjunction + : `e` `e` sequence + : `e` * Kleene star + : emp empty + : eps epsilon + : ( `e` ) + + The `emp` regexp does not match any search path while `eps` + matches the empty path. During proof search, the path of + successive successful hints on a search branch is recorded, as a + list of identifiers for the hints (note that Hint Extern’s do not have + an associated identifier). + Before applying any hint :n:`@ident` the current path `p` extended with + :n:`@ident` is matched against the current cut expression `c` associated to + the hint database. If matching succeeds, the hint is *not* applied. The + semantics of ``Hint Cut e`` is to set the cut expression to ``c | e``, the + initial cut expression being `emp`. + + .. cmdv:: Hint Mode @qualid {* (+ | ! | -)} : @ident + :name: Hint Mode + + This sets an optional mode of use of the identifier :n:`@qualid`. When + proof-search faces a goal that ends in an application of :n:`@qualid` to + arguments :n:`@term ... @term`, the mode tells if the hints associated to + :n:`@qualid` can be applied or not. A mode specification is a list of n ``+``, + ``!`` or ``-`` items that specify if an argument of the identifier is to be + treated as an input (``+``), if its head only is an input (``!``) or an output + (``-``) of the identifier. For a mode to match a list of arguments, input + terms and input heads *must not* contain existential variables or be + existential variables respectively, while outputs can be any term. Multiple + modes can be declared for a single identifier, in that case only one mode + needs to match the arguments for the hints to be applied.The head of a term + is understood here as the applicative head, or the match or projection + scrutinee’s head, recursively, casts being ignored. ``Hint Mode`` is + especially useful for typeclasses, when one does not want to support default + instances and avoid ambiguity in general. Setting a parameter of a class as an + input forces proof-search to be driven by that index of the class, with ``!`` + giving more flexibility by allowing existentials to still appear deeper in the + index but not at its head. + + .. note:: + + One can use an ``Extern`` hint with no pattern to do pattern matching on + hypotheses using ``match goal`` with inside the tactic. + + +Hint databases defined in the Coq standard library +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Several hint databases are defined in the Coq standard library. The +actual content of a database is the collection of hints declared +to belong to this database in each of the various modules currently +loaded. Especially, requiring new modules may extend the database. +At Coq startup, only the core database is nonempty and can be used. + +:core: This special database is automatically used by ``auto``, except when + pseudo-database ``nocore`` is given to ``auto``. The core database + contains only basic lemmas about negation, conjunction, and so on. + Most of the hints in this database come from the Init and Logic directories. + +:arith: This database contains all lemmas about Peano’s arithmetic proved in the + directories Init and Arith. + +:zarith: contains lemmas about binary signed integers from the directories + theories/ZArith. When required, the module Omega also extends the + database zarith with a high-cost hint that calls ``omega`` on equations + and inequalities in ``nat`` or ``Z``. + +:bool: contains lemmas about booleans, mostly from directory theories/Bool. + +:datatypes: is for lemmas about lists, streams and so on that are mainly proved + in the Lists subdirectory. + +:sets: contains lemmas about sets and relations from the directories Sets and + Relations. + +:typeclass_instances: contains all the typeclass instances declared in the + environment, including those used for ``setoid_rewrite``, + from the Classes directory. + +:fset: internal database for the implementation of the ``FSets`` library. + +You are advised not to put your own hints in the core database, but +use one or several databases specific to your development. + +.. _removehints: + +.. cmd:: Remove Hints {+ @term} : {+ @ident} + + This command removes the hints associated to terms :n:`{+ @term}` in databases + :n:`{+ @ident}`. + +.. _printhint: + +.. cmd:: Print Hint + + This command displays all hints that apply to the current goal. It + fails if no proof is being edited, while the two variants can be used + at every moment. + +**Variants:** + + +.. cmd:: Print Hint @ident + + This command displays only tactics associated with :n:`@ident` in the hints + list. This is independent of the goal being edited, so this command will not + fail if no goal is being edited. + +.. cmd:: Print Hint * + + This command displays all declared hints. + +.. cmd:: Print HintDb @ident + + This command displays all hints from database :n:`@ident`. + +.. _hintrewrite: + +.. cmd:: Hint Rewrite {+ @term} : {+ @ident} + + This vernacular command adds the terms :n:`{+ @term}` (their types must be + equalities) in the rewriting bases :n:`{+ @ident}` with the default orientation + (left to right). Notice that the rewriting bases are distinct from the ``auto`` + hint bases and thatauto does not take them into account. + + This command is synchronous with the section mechanism (see :ref:`section-mechanism`): + when closing a section, all aliases created by ``Hint Rewrite`` in that + section are lost. Conversely, when loading a module, all ``Hint Rewrite`` + declarations at the global level of that module are loaded. + +**Variants:** + +.. cmd:: Hint Rewrite -> {+ @term} : {+ @ident} + + This is strictly equivalent to the command above (we only make explicit the + orientation which otherwise defaults to ->). + +.. cmd:: Hint Rewrite <- {+ @term} : {+ @ident} + + Adds the rewriting rules :n:`{+ @term}` with a right-to-left orientation in + the bases :n:`{+ @ident}`. + +.. cmd:: Hint Rewrite {+ @term} using tactic : {+ @ident} + + When the rewriting rules :n:`{+ @term}` in :n:`{+ @ident}` will be used, the + tactic ``tactic`` will be applied to the generated subgoals, the main subgoal + excluded. + +.. cmd:: Print Rewrite HintDb @ident + + This command displays all rewrite hints contained in :n:`@ident`. + +Hint locality +~~~~~~~~~~~~~ + +Hints provided by the ``Hint`` commands are erased when closing a section. +Conversely, all hints of a module ``A`` that are not defined inside a +section (and not defined with option ``Local``) become available when the +module ``A`` is imported (using e.g. ``Require Import A.``). + +As of today, hints only have a binary behavior regarding locality, as +described above: either they disappear at the end of a section scope, +or they remain global forever. This causes a scalability issue, +because hints coming from an unrelated part of the code may badly +influence another development. It can be mitigated to some extent +thanks to the :cmd:`Remove Hints` command, +but this is a mere workaround and has some limitations (for instance, external +hints cannot be removed). + +A proper way to fix this issue is to bind the hints to their module scope, as +for most of the other objects Coq uses. Hints should only be made available when +the module they are defined in is imported, not just required. It is very +difficult to change the historical behavior, as it would break a lot of scripts. +We propose a smooth transitional path by providing the :opt:`Loose Hint Behavior` +option which accepts three flags allowing for a fine-grained handling of +non-imported hints. + +.. opt:: Loose Hint Behavior %( "Lax" %| "Warn" %| "Strict" %) + :name: Loose Hint Behavior + + This option accepts three values, which control the behavior of hints w.r.t. + :cmd:`Import`: + + - "Lax": this is the default, and corresponds to the historical behavior, + that is, hints defined outside of a section have a global scope. + + - "Warn": outputs a warning when a non-imported hint is used. Note that this + is an over-approximation, because a hint may be triggered by a run that + will eventually fail and backtrack, resulting in the hint not being + actually useful for the proof. + + - "Strict": changes the behavior of an unloaded hint to a immediate fail + tactic, allowing to emulate an import-scoped hint mechanism. + +.. _tactics-implicit-automation: + +Setting implicit automation tactics +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. cmd:: Proof with @tactic + + This command may be used to start a proof. It defines a default tactic + to be used each time a tactic command ``tactic``:sub:`1` is ended by ``...``. + In this case the tactic command typed by the user is equivalent to + ``tactic``:sub:`1` ``;tactic``. + + .. seealso:: :cmd:`Proof` in :ref:`proof-editing-mode`. + + + .. cmdv:: Proof with tactic using {+ @ident} + + Combines in a single line ``Proof with`` and ``Proof using``, see :ref:`proof-editing-mode` + + .. cmdv:: Proof using {+ @ident} with @tactic + + Combines in a single line ``Proof with`` and ``Proof using``, see :ref:`proof-editing-mode` + +.. _decisionprocedures: + +Decision procedures +------------------- + +.. tacn:: tauto + :name: tauto + + This tactic implements a decision procedure for intuitionistic propositional + calculus based on the contraction-free sequent calculi LJT* of Roy Dyckhoff + :cite:`Dyc92`. Note that :tacn:`tauto` succeeds on any instance of an + intuitionistic tautological proposition. :tacn:`tauto` unfolds negations and + logical equivalence but does not unfold any other definition. + +.. example:: + + The following goal can be proved by :tacn:`tauto` whereas :tacn:`auto` would + fail: + + .. coqtop:: reset all + + Goal forall (x:nat) (P:nat -> Prop), x = 0 \/ P x -> x <> 0 -> P x. + intros. + tauto. + +Moreover, if it has nothing else to do, :tacn:`tauto` performs introductions. +Therefore, the use of :tacn:`intros` in the previous proof is unnecessary. +:tacn:`tauto` can for instance for: + +.. example:: + + .. coqtop:: reset all + + Goal forall (A:Prop) (P:nat -> Prop), A \/ (forall x:nat, ~ A -> P x) -> forall x:nat, ~ A -> P x. + tauto. + +.. note:: + In contrast, :tacn:`tauto` cannot solve the following goal + :g:`Goal forall (A:Prop) (P:nat -> Prop), A \/ (forall x:nat, ~ A -> P x) ->` + :g:`forall x:nat, ~ ~ (A \/ P x).` + because :g:`(forall x:nat, ~ A -> P x)` cannot be treated as atomic and + an instantiation of `x` is necessary. + +.. tacv:: dtauto + :name: dtauto + + While :tacn:`tauto` recognizes inductively defined connectives isomorphic to + the standard connectives ``and``, ``prod``, ``or``, ``sum``, ``False``, + ``Empty_set``, ``unit``, ``True``, :tacn:`dtauto` also recognizes all inductive + types with one constructor and no indices, i.e. record-style connectives. + +.. tacn:: intuition @tactic + :name: intuition + + The tactic :tacn:`intuition` takes advantage of the search-tree built by the + decision procedure involved in the tactic :tacn:`tauto`. It uses this + information to generate a set of subgoals equivalent to the original one (but + simpler than it) and applies the tactic :n:`@tactic` to them :cite:`Mun94`. If + this tactic fails on some goals then :tacn:`intuition` fails. In fact, + :tacn:`tauto` is simply :g:`intuition fail`. + + .. example:: + + For instance, the tactic :g:`intuition auto` applied to the goal:: + + (forall (x:nat), P x) /\ B -> (forall (y:nat), P y) /\ P O \/ B /\ P O + + internally replaces it by the equivalent one:: + + (forall (x:nat), P x), B |- P O + + and then uses :tacn:`auto` which completes the proof. + +Originally due to César Muñoz, these tactics (:tacn:`tauto` and +:tacn:`intuition`) have been completely re-engineered by David Delahaye using +mainly the tactic language (see :ref:`ltac`). The code is +now much shorter and a significant increase in performance has been noticed. +The general behavior with respect to dependent types, unfolding and +introductions has slightly changed to get clearer semantics. This may lead to +some incompatibilities. + +.. tacv:: intuition + + Is equivalent to :g:`intuition auto with *`. + +.. tacv:: dintuition + :name: dintuition + + While :tacn:`intuition` recognizes inductively defined connectives + isomorphic to the standard connectives ``and``, ``prod``, ``or``, ``sum``, ``False``, + ``Empty_set``, ``unit``, ``True``, :tacn:`dintuition` also recognizes all inductive + types with one constructor and no indices, i.e. record-style connectives. + +.. flag:: Intuition Negation Unfolding + + Controls whether :tacn:`intuition` unfolds inner negations which do not need + to be unfolded. This option is on by default. + +.. tacn:: rtauto + :name: rtauto + + The :tacn:`rtauto` tactic solves propositional tautologies similarly to what + :tacn:`tauto` does. The main difference is that the proof term is built using a + reflection scheme applied to a sequent calculus proof of the goal. The search + procedure is also implemented using a different technique. + + Users should be aware that this difference may result in faster proof-search + but slower proof-checking, and :tacn:`rtauto` might not solve goals that + :tacn:`tauto` would be able to solve (e.g. goals involving universal + quantifiers). + + Note that this tactic is only available after a ``Require Import Rtauto``. + +.. tacn:: firstorder + :name: firstorder + + The tactic :tacn:`firstorder` is an experimental extension of :tacn:`tauto` to + first- order reasoning, written by Pierre Corbineau. It is not restricted to + usual logical connectives but instead may reason about any first-order class + inductive definition. + +.. opt:: Firstorder Solver @tactic + :name: Firstorder Solver + + The default tactic used by :tacn:`firstorder` when no rule applies is + :g:`auto with *`, it can be reset locally or globally using this option. + + .. cmd:: Print Firstorder Solver + + Prints the default tactic used by :tacn:`firstorder` when no rule applies. + +.. tacv:: firstorder @tactic + + Tries to solve the goal with :n:`@tactic` when no logical rule may apply. + +.. tacv:: firstorder using {+ @qualid} + + Adds lemmas :n:`{+ @qualid}` to the proof-search environment. If :n:`@qualid` + refers to an inductive type, it is the collection of its constructors which are + added to the proof-search environment. + +.. tacv:: firstorder with {+ @ident} + + Adds lemmas from :tacn:`auto` hint bases :n:`{+ @ident}` to the proof-search + environment. + +.. tacv:: firstorder tactic using {+ @qualid} with {+ @ident} + + This combines the effects of the different variants of :tacn:`firstorder`. + +.. opt:: Firstorder Depth @num + :name: Firstorder Depth + + This option controls the proof-search depth bound. + +.. tacn:: congruence + :name: congruence + + The tactic :tacn:`congruence`, by Pierre Corbineau, implements the standard + Nelson and Oppen congruence closure algorithm, which is a decision procedure + for ground equalities with uninterpreted symbols. It also includes + constructor theory (see :tacn:`injection` and :tacn:`discriminate`). If the goal + is a non-quantified equality, congruence tries to prove it with non-quantified + equalities in the context. Otherwise it tries to infer a discriminable equality + from those in the context. Alternatively, congruence tries to prove that a + hypothesis is equal to the goal or to the negation of another hypothesis. + + :tacn:`congruence` is also able to take advantage of hypotheses stating + quantified equalities, but you have to provide a bound for the number of extra + equalities generated that way. Please note that one of the sides of the + equality must contain all the quantified variables in order for congruence to + match against it. + +.. example:: + + .. coqtop:: reset all + + Theorem T (A:Type) (f:A -> A) (g: A -> A -> A) a b: a=(f a) -> (g b (f a))=(f (f a)) -> (g a b)=(f (g b a)) -> (g a b)=a. + intros. + congruence. + Qed. + + Theorem inj (A:Type) (f:A -> A * A) (a c d: A) : f = pair a -> Some (f c) = Some (f d) -> c=d. + intros. + congruence. + Qed. + +.. tacv:: congruence n + + Tries to add at most `n` instances of hypotheses stating quantified equalities + to the problem in order to solve it. A bigger value of `n` does not make + success slower, only failure. You might consider adding some lemmas as + hypotheses using assert in order for :tacn:`congruence` to use them. + +.. tacv:: congruence with {+ @term} + :name: congruence with + + Adds :n:`{+ @term}` to the pool of terms used by :tacn:`congruence`. This helps + in case you have partially applied constructors in your goal. + +.. exn:: I don’t know how to handle dependent equality. + + The decision procedure managed to find a proof of the goal or of a + discriminable equality but this proof could not be built in Coq because of + dependently-typed functions. + +.. exn:: Goal is solvable by congruence but some arguments are missing. Try congruence with {+ @term}, replacing metavariables by arbitrary terms. + + The decision procedure could solve the goal with the provision that additional + arguments are supplied for some partially applied constructors. Any term of an + appropriate type will allow the tactic to successfully solve the goal. Those + additional arguments can be given to congruence by filling in the holes in the + terms given in the error message, using the :tacn:`congruence with` variant described above. + +.. flag:: Congruence Verbose + + This option makes :tacn:`congruence` print debug information. + + +Checking properties of terms +---------------------------- + +Each of the following tactics acts as the identity if the check +succeeds, and results in an error otherwise. + +.. tacn:: constr_eq @term @term + :name: constr_eq + + This tactic checks whether its arguments are equal modulo alpha + conversion, casts and universe constraints. It may unify universes. + +.. exn:: Not equal. + :undocumented: + +.. exn:: Not equal (due to universes). + :undocumented: + +.. tacn:: constr_eq_strict @term @term + :name: constr_eq_strict + + This tactic checks whether its arguments are equal modulo alpha + conversion, casts and universe constraints. It does not add new + constraints. + +.. exn:: Not equal. + :undocumented: + +.. exn:: Not equal (due to universes). + :undocumented: + +.. tacn:: unify @term @term + :name: unify + + This tactic checks whether its arguments are unifiable, potentially + instantiating existential variables. + +.. exn:: Unable to unify @term with @term. + :undocumented: + +.. tacv:: unify @term @term with @ident + + Unification takes the transparency information defined in the hint database + :n:`@ident` into account (see :ref:`the hints databases for auto and eauto <thehintsdatabasesforautoandeauto>`). + +.. tacn:: is_evar @term + :name: is_evar + + This tactic checks whether its argument is a current existential + variable. Existential variables are uninstantiated variables generated + by :tacn:`eapply` and some other tactics. + +.. exn:: Not an evar. + :undocumented: + +.. tacn:: has_evar @term + :name: has_evar + + This tactic checks whether its argument has an existential variable as + a subterm. Unlike context patterns combined with ``is_evar``, this tactic + scans all subterms, including those under binders. + +.. exn:: No evars. + :undocumented: + +.. tacn:: is_var @term + :name: is_var + + This tactic checks whether its argument is a variable or hypothesis in + the current goal context or in the opened sections. + +.. exn:: Not a variable or hypothesis. + :undocumented: + + +.. _equality: + +Equality +-------- + + +.. tacn:: f_equal + :name: f_equal + + This tactic applies to a goal of the form :g:`f a`:sub:`1` :g:`... a`:sub:`n` + :g:`= f′a′`:sub:`1` :g:`... a′`:sub:`n`. Using :tacn:`f_equal` on such a goal + leads to subgoals :g:`f=f′` and :g:`a`:sub:`1` = :g:`a′`:sub:`1` and so on up + to :g:`a`:sub:`n` :g:`= a′`:sub:`n`. Amongst these subgoals, the simple ones + (e.g. provable by :tacn:`reflexivity` or :tacn:`congruence`) are automatically + solved by :tacn:`f_equal`. + + +.. tacn:: reflexivity + :name: reflexivity + + This tactic applies to a goal that has the form :g:`t=u`. It checks that `t` + and `u` are convertible and then solves the goal. It is equivalent to + ``apply refl_equal``. + + .. exn:: The conclusion is not a substitutive equation. + :undocumented: + + .. exn:: Unable to unify ... with ... + :undocumented: + + +.. tacn:: symmetry + :name: symmetry + + This tactic applies to a goal that has the form :g:`t=u` and changes it into + :g:`u=t`. + + +.. tacv:: symmetry in @ident + + If the statement of the hypothesis ident has the form :g:`t=u`, the tactic + changes it to :g:`u=t`. + + +.. tacn:: transitivity @term + :name: transitivity + + This tactic applies to a goal that has the form :g:`t=u` and transforms it + into the two subgoals :n:`t=@term` and :n:`@term=u`. + + +Equality and inductive sets +--------------------------- + +We describe in this section some special purpose tactics dealing with +equality and inductive sets or types. These tactics use the +equality :g:`eq:forall (A:Type), A->A->Prop`, simply written with the infix +symbol :g:`=`. + +.. tacn:: decide equality + :name: decide equality + + This tactic solves a goal of the form :g:`forall x y : R, {x = y} + {~ x = y}`, + where :g:`R` is an inductive type such that its constructors do not take + proofs or functions as arguments, nor objects in dependent types. It + solves goals of the form :g:`{x = y} + {~ x = y}` as well. + +.. tacn:: compare @term @term + :name: compare + + This tactic compares two given objects :n:`@term` and :n:`@term` of an + inductive datatype. If :g:`G` is the current goal, it leaves the sub- + goals :n:`@term =@term -> G` and :n:`~ @term = @term -> G`. The type of + :n:`@term` and :n:`@term` must satisfy the same restrictions as in the + tactic ``decide equality``. + +.. tacn:: simplify_eq @term + :name: simplify_eq + + Let :n:`@term` be the proof of a statement of conclusion :n:`@term = @term`. + If :n:`@term` and :n:`@term` are structurally different (in the sense + described for the tactic :tacn:`discriminate`), then the tactic + ``simplify_eq`` behaves as :n:`discriminate @term`, otherwise it behaves as + :n:`injection @term`. + +.. note:: + If some quantified hypothesis of the goal is named :n:`@ident`, + then :n:`simplify_eq @ident` first introduces the hypothesis in the local + context using :n:`intros until @ident`. + +.. tacv:: simplify_eq @num + + This does the same thing as :n:`intros until @num` then + :n:`simplify_eq @ident` where :n:`@ident` is the identifier for the last + introduced hypothesis. + +.. tacv:: simplify_eq @term with @bindings_list + + This does the same as :n:`simplify_eq @term` but using the given bindings to + instantiate parameters or hypotheses of :n:`@term`. + +.. tacv:: esimplify_eq @num + esimplify_eq @term {? with @bindings_list} + :name: esimplify_eq; _ + + This works the same as :tacn:`simplify_eq` but if the type of :n:`@term`, or the + type of the hypothesis referred to by :n:`@num`, has uninstantiated + parameters, these parameters are left as existential variables. + +.. tacv:: simplify_eq + + If the current goal has form :g:`t1 <> t2`, it behaves as + :n:`intro @ident; simplify_eq @ident`. + +.. tacn:: dependent rewrite -> @ident + :name: dependent rewrite -> + + This tactic applies to any goal. If :n:`@ident` has type + :g:`(existT B a b)=(existT B a' b')` in the local context (i.e. each + :n:`@term` of the equality has a sigma type :g:`{ a:A & (B a)}`) this tactic + rewrites :g:`a` into :g:`a'` and :g:`b` into :g:`b'` in the current goal. + This tactic works even if :g:`B` is also a sigma type. This kind of + equalities between dependent pairs may be derived by the + :tacn:`injection` and :tacn:`inversion` tactics. + +.. tacv:: dependent rewrite <- @ident + :name: dependent rewrite <- + + Analogous to :tacn:`dependent rewrite ->` but uses the equality from right to + left. + +Inversion +--------- + +.. tacn:: functional inversion @ident + :name: functional inversion + + :tacn:`functional inversion` is a tactic that performs inversion on hypothesis + :n:`@ident` of the form :n:`@qualid {+ @term} = @term` or :n:`@term = @qualid + {+ @term}` where :n:`@qualid` must have been defined using Function (see + :ref:`advanced-recursive-functions`). Note that this tactic is only + available after a ``Require Import FunInd``. + + .. exn:: Hypothesis @ident must contain at least one Function. + :undocumented: + + .. exn:: Cannot find inversion information for hypothesis @ident. + + This error may be raised when some inversion lemma failed to be generated by + Function. + + + .. tacv:: functional inversion @num + + This does the same thing as :n:`intros until @num` folowed by + :n:`functional inversion @ident` where :token:`ident` is the + identifier for the last introduced hypothesis. + + .. tacv:: functional inversion @ident @qualid + functional inversion @num @qualid + + If the hypothesis :token:`ident` (or :token:`num`) has a type of the form + :n:`@qualid__1 {+ @term__i } = @qualid__2 {+ @term__j }` where + :n:`@qualid__1` and :n:`@qualid__2` are valid candidates to + functional inversion, this variant allows choosing which :token:`qualid` + is inverted. + +Classical tactics +----------------- + +In order to ease the proving process, when the Classical module is +loaded. A few more tactics are available. Make sure to load the module +using the ``Require Import`` command. + +.. tacn:: classical_left + classical_right + :name: classical_left; classical_right + + These tactics are the analog of :tacn:`left` and :tacn:`right` + but using classical logic. They can only be used for + disjunctions. Use :tacn:`classical_left` to prove the left part of the + disjunction with the assumption that the negation of right part holds. + Use :tacn:`classical_right` to prove the right part of the disjunction with + the assumption that the negation of left part holds. + +.. _tactics-automating: + +Automating +------------ + + +.. tacn:: btauto + :name: btauto + + The tactic :tacn:`btauto` implements a reflexive solver for boolean + tautologies. It solves goals of the form :g:`t = u` where `t` and `u` are + constructed over the following grammar: + + .. _btauto_grammar: + + .. productionlist:: sentence + t : `x` + : true + : false + : orb `t` `t` + : andb `t` `t` + : xorb `t` `t` + : negb `t` + : if `t` then `t` else `t` + + Whenever the formula supplied is not a tautology, it also provides a + counter-example. + + Internally, it uses a system very similar to the one of the ring + tactic. + + Note that this tactic is only available after a ``Require Import Btauto``. + + .. exn:: Cannot recognize a boolean equality. + + The goal is not of the form :g:`t = u`. Especially note that :tacn:`btauto` + doesn't introduce variables into the context on its own. + +.. tacn:: omega + :name: omega + + The tactic :tacn:`omega`, due to Pierre Crégut, is an automatic decision + procedure for Presburger arithmetic. It solves quantifier-free + formulas built with `~`, `\/`, `/\`, `->` on top of equalities, + inequalities and disequalities on both the type :g:`nat` of natural numbers + and :g:`Z` of binary integers. This tactic must be loaded by the command + ``Require Import Omega``. See the additional documentation about omega + (see Chapter :ref:`omega`). + + +.. tacn:: ring + :name: ring + + This tactic solves equations upon polynomial expressions of a ring + (or semiring) structure. It proceeds by normalizing both hand sides + of the equation (w.r.t. associativity, commutativity and + distributivity, constant propagation) and comparing syntactically the + results. + +.. tacn:: ring_simplify {* @term} + :name: ring_simplify + + This tactic applies the normalization procedure described above to + the given terms. The tactic then replaces all occurrences of the terms + given in the conclusion of the goal by their normal forms. If no term + is given, then the conclusion should be an equation and both hand + sides are normalized. + +See :ref:`Theringandfieldtacticfamilies` for more information on +the tactic and how to declare new ring structures. All declared field structures +can be printed with the ``Print Rings`` command. + +.. tacn:: field + field_simplify {* @term} + field_simplify_eq + :name: field; field_simplify; field_simplify_eq + + The field tactic is built on the same ideas as ring: this is a + reflexive tactic that solves or simplifies equations in a field + structure. The main idea is to reduce a field expression (which is an + extension of ring expressions with the inverse and division + operations) to a fraction made of two polynomial expressions. + + Tactic :n:`field` is used to solve subgoals, whereas :n:`field_simplify {+ @term}` + replaces the provided terms by their reduced fraction. + :n:`field_simplify_eq` applies when the conclusion is an equation: it + simplifies both hand sides and multiplies so as to cancel + denominators. So it produces an equation without division nor inverse. + + All of these 3 tactics may generate a subgoal in order to prove that + denominators are different from zero. + + See :ref:`Theringandfieldtacticfamilies` for more information on the tactic and how to + declare new field structures. All declared field structures can be + printed with the Print Fields command. + +.. example:: + + .. coqtop:: reset all + + Require Import Reals. + Goal forall x y:R, + (x * y > 0)%R -> + (x * (1 / x + x / (x + y)))%R = + ((- 1 / y) * y * (- x * (x / (x + y)) - 1))%R. + + intros; field. + +.. seealso:: + + File plugins/setoid_ring/RealField.v for an example of instantiation, + theory theories/Reals for many examples of use of field. + +Non-logical tactics +------------------------ + + +.. tacn:: cycle @num + :name: cycle + + This tactic puts the :n:`@num` first goals at the end of the list of goals. + If :n:`@num` is negative, it will put the last :math:`|num|` goals at the + beginning of the list. + +.. example:: + + .. coqtop:: all reset + + Parameter P : nat -> Prop. + Goal P 1 /\ P 2 /\ P 3 /\ P 4 /\ P 5. + repeat split. + all: cycle 2. + all: cycle -3. + +.. tacn:: swap @num @num + :name: swap + + This tactic switches the position of the goals of indices :n:`@num` and + :n:`@num`. If either :n:`@num` or :n:`@num` is negative then goals are + counted from the end of the focused goal list. Goals are indexed from 1, + there is no goal with position 0. + +.. example:: + + .. coqtop:: reset all + + Parameter P : nat -> Prop. + Goal P 1 /\ P 2 /\ P 3 /\ P 4 /\ P 5. + repeat split. + all: swap 1 3. + all: swap 1 -1. + +.. tacn:: revgoals + :name: revgoals + + This tactics reverses the list of the focused goals. + + .. example:: + + .. coqtop:: all reset + + Parameter P : nat -> Prop. + Goal P 1 /\ P 2 /\ P 3 /\ P 4 /\ P 5. + repeat split. + all: revgoals. + +.. tacn:: shelve + :name: shelve + + This tactic moves all goals under focus to a shelf. While on the + shelf, goals will not be focused on. They can be solved by + unification, or they can be called back into focus with the command + :cmd:`Unshelve`. + + .. tacv:: shelve_unifiable + :name: shelve_unifiable + + Shelves only the goals under focus that are mentioned in other goals. + Goals that appear in the type of other goals can be solved by unification. + + .. example:: + + .. coqtop:: all reset + + Goal exists n, n=0. + refine (ex_intro _ _ _). + all: shelve_unifiable. + reflexivity. + +.. cmd:: Unshelve + + This command moves all the goals on the shelf (see :tacn:`shelve`) + from the shelf into focus, by appending them to the end of the current + list of focused goals. + +.. tacn:: give_up + :name: give_up + + This tactic removes the focused goals from the proof. They are not + solved, and cannot be solved later in the proof. As the goals are not + solved, the proof cannot be closed. + + The ``give_up`` tactic can be used while editing a proof, to choose to + write the proof script in a non-sequential order. + +Simple tactic macros +------------------------- + +A simple example has more value than a long explanation: + +.. example:: + + .. coqtop:: reset all + + Ltac Solve := simpl; intros; auto. + + Ltac ElimBoolRewrite b H1 H2 := + elim b; [ intros; rewrite H1; eauto | intros; rewrite H2; eauto ]. + +The tactics macros are synchronous with the Coq section mechanism: a +tactic definition is deleted from the current environment when you +close the section (see also :ref:`section-mechanism`) where it was +defined. If you want that a tactic macro defined in a module is usable in the +modules that require it, you should put it outside of any section. + +:ref:`ltac` gives examples of more complex +user-defined tactics. + +.. [1] Actually, only the second subgoal will be generated since the + other one can be automatically checked. +.. [2] This corresponds to the cut rule of sequent calculus. +.. [3] Reminder: opaque constants will not be expanded by δ reductions. +.. [4] The behavior of this tactic has changed a lot compared to the + versions available in the previous distributions (V6). This may cause + significant changes in your theories to obtain the same result. As a + drawback of the re-engineering of the code, this tactic has also been + completely revised to get a very compact and readable version. + +Delaying solving unification constraints +---------------------------------------- + +.. tacn:: solve_constraints + :name: solve_constraints + :undocumented: + +.. flag:: Solve Unification Constraints + + By default, after each tactic application, postponed typechecking unification + problems are resolved using heuristics. Unsetting this flag disables this + behavior, allowing tactics to leave unification constraints unsolved. Use the + :tacn:`solve_constraints` tactic at any point to solve the constraints. + +Proof maintenance +----------------- + +*Experimental.* Many tactics, such as :tacn:`intros`, can automatically generate names, such +as "H0" or "H1" for a new hypothesis introduced from a goal. Subsequent proof steps +may explicitly refer to these names. However, future versions of Coq may not assign +names exactly the same way, which could cause the proof to fail because the +new names don't match the explicit references in the proof. + +The following "Mangle Names" settings let users find all the +places where proofs rely on automatically generated names, which can +then be named explicitly to avoid any incompatibility. These +settings cause Coq to generate different names, producing errors for +references to automatically generated names. + +.. flag:: Mangle Names + + When set, generated names use the prefix specified in the following + option instead of the default prefix. + +.. opt:: Mangle Names Prefix @string + :name: Mangle Names Prefix + + Specifies the prefix to use when generating names. diff --git a/doc/sphinx/proof-engine/vernacular-commands.rst b/doc/sphinx/proof-engine/vernacular-commands.rst new file mode 100644 index 0000000000..e207a072cc --- /dev/null +++ b/doc/sphinx/proof-engine/vernacular-commands.rst @@ -0,0 +1,1282 @@ +.. _vernacularcommands: + +Vernacular commands +============================= + +.. _displaying: + +Displaying +-------------- + + +.. _Print: + +.. cmd:: Print @qualid + :name: Print + + This command displays on the screen information about the declared or + defined object referred by :n:`@qualid`. + + Error messages: + + .. exn:: @qualid not a defined object. + :undocumented: + + .. exn:: Universe instance should have length @num. + :undocumented: + + .. exn:: This object does not support universe names. + :undocumented: + + + .. cmdv:: Print Term @qualid + :name: Print Term + + This is a synonym of :cmd:`Print` :n:`@qualid` when :n:`@qualid` + denotes a global constant. + + .. cmdv:: Print {? Term } @qualid\@@name + + This locally renames the polymorphic universes of :n:`@qualid`. + An underscore means the usual name is printed. + + +.. cmd:: About @qualid + :name: About + + This displays various information about the object + denoted by :n:`@qualid`: its kind (module, constant, assumption, inductive, + constructor, abbreviation, …), long name, type, implicit arguments and + argument scopes. It does not print the body of definitions or proofs. + + .. cmdv:: About @qualid\@@name + + This locally renames the polymorphic universes of :n:`@qualid`. + An underscore means the usual name is printed. + + +.. cmd:: Print All + + This command displays information about the current state of the + environment, including sections and modules. + + .. cmdv:: Inspect @num + :name: Inspect + + This command displays the :n:`@num` last objects of the + current environment, including sections and modules. + + .. cmdv:: Print Section @ident + + The name :n:`@ident` should correspond to a currently open section, + this command displays the objects defined since the beginning of this + section. + + +.. _flags-options-tables: + +Flags, Options and Tables +----------------------------- + +Coq has many settings to control its behavior. Setting types include flags, options +and tables: + +* A :production:`flag` has a boolean value, such as :flag:`Asymmetric Patterns`. +* An :production:`option` generally has a numeric or string value, such as :opt:`Firstorder Depth`. +* A :production:`table` contains a set of strings or qualids. +* In addition, some commands provide settings, such as :cmd:`Extraction Language`. + +.. FIXME Convert "Extraction Language" to an option. + +Flags, options and tables are identified by a series of identifiers, each with an initial +capital letter. + +.. cmd:: {? Local | Global | Export } Set @flag + :name: Set + + Sets :token:`flag` on. Scoping qualifiers are + described :ref:`here <set_unset_scope_qualifiers>`. + +.. cmd:: {? Local | Global | Export } Unset @flag + :name: Unset + + Sets :token:`flag` off. Scoping qualifiers are + described :ref:`here <set_unset_scope_qualifiers>`. + +.. cmd:: Test @flag + + Prints the current value of :token:`flag`. + + +.. cmd:: {? Local | Global | Export } Set @option ( @num | @string ) + :name: Set @option + + Sets :token:`option` to the specified value. Scoping qualifiers are + described :ref:`here <set_unset_scope_qualifiers>`. + +.. cmd:: {? Local | Global | Export } Unset @option + :name: Unset @option + + Sets :token:`option` to its default value. Scoping qualifiers are + described :ref:`here <set_unset_scope_qualifiers>`. + +.. cmd:: Test @option + + Prints the current value of :token:`option`. + +.. cmd:: Print Options + + Prints the current value of all flags and options, and the names of all tables. + + +.. cmd:: Add @table ( @string | @qualid ) + :name: Add @table + + Adds the specified value to :token:`table`. + +.. cmd:: Remove @table ( @string | @qualid ) + :name: Remove @table + + Removes the specified value from :token:`table`. + +.. cmd:: Test @table for ( @string | @qualid ) + :name: Test @table for + + Reports whether :token:`table` contains the specified value. + +.. cmd:: Print Table @table + :name: Print Table @table + + Prints the values in :token:`table`. + +.. cmd:: Test @table + + A synonym for :cmd:`Print Table @table`. + +.. cmd:: Print Tables + + A synonym for :cmd:`Print Options`. + +.. _set_unset_scope_qualifiers: + +Scope qualifiers for :cmd:`Set` and :cmd:`Unset` +````````````````````````````````````````````````` + +:n:`{? Local | Global | Export }` + +Flag and option settings can be global in scope or local to nested scopes created by +:cmd:`Module` and :cmd:`Section` commands. There are four alternatives: + +* no qualifier: the original setting is *not* restored at the end of the current module or section. +* **Local**: the setting is applied within the current scope. The original value of the option + or flag is restored at the end of the current module or section. +* **Global**: similar to no qualifier, the original setting is *not* restored at the end of the current + module or section. In addition, if the value is set in a file, then :cmd:`Require`-ing + the file sets the option. +* **Export**: similar to **Local**, the original value of the option or flag is restored at the + end of the current module or section. In addition, if the value is set in a file, then :cmd:`Import`-ing + the file sets the option. + +Newly opened scopes inherit the current settings. + +.. _requests-to-the-environment: + +Requests to the environment +------------------------------- + +.. cmd:: Check @term + + This command displays the type of :n:`@term`. When called in proof mode, the + term is checked in the local context of the current subgoal. + + + .. TODO : selector is not a syntax entry + + .. cmdv:: @selector: Check @term + + This variant specifies on which subgoal to perform typing + (see Section :ref:`invocation-of-tactics`). + + +.. TODO : convtactic is not a syntax entry + +.. cmd:: Eval @convtactic in @term + + This command performs the specified reduction on :n:`@term`, and displays + the resulting term with its type. The term to be reduced may depend on + hypothesis introduced in the first subgoal (if a proof is in + progress). + + .. seealso:: Section :ref:`performingcomputations`. + + +.. cmd:: Compute @term + + This command performs a call-by-value evaluation of term by using the + bytecode-based virtual machine. It is a shortcut for ``Eval vm_compute in`` + :n:`@term`. + + .. seealso:: Section :ref:`performingcomputations`. + + +.. cmd:: Print Assumptions @qualid + + This commands display all the assumptions (axioms, parameters and + variables) a theorem or definition depends on. Especially, it informs + on the assumptions with respect to which the validity of a theorem + relies. + + .. cmdv:: Print Opaque Dependencies @qualid + :name: Print Opaque Dependencies + + Displays the set of opaque constants :n:`@qualid` relies on in addition to + the assumptions. + + .. cmdv:: Print Transparent Dependencies @qualid + :name: Print Transparent Dependencies + + Displays the set of transparent constants :n:`@qualid` relies on + in addition to the assumptions. + + .. cmdv:: Print All Dependencies @qualid + :name: Print All Dependencies + + Displays all assumptions and constants :n:`@qualid` relies on. + + +.. cmd:: Search @qualid + + This command displays the name and type of all objects (hypothesis of + the current goal, theorems, axioms, etc) of the current context whose + statement contains :n:`@qualid`. This command is useful to remind the user + of the name of library lemmas. + + .. exn:: The reference @qualid was not found in the current environment. + + There is no constant in the environment named qualid. + + .. cmdv:: Search @string + + If :n:`@string` is a valid identifier, this command + displays the name and type of all objects (theorems, axioms, etc) of + the current context whose name contains string. If string is a + notation’s string denoting some reference :n:`@qualid` (referred to by its + main symbol as in `"+"` or by its notation’s string as in `"_ + _"` or + `"_ 'U' _"`, see Section :ref:`notations`), the command works like ``Search`` :n:`@qualid`. + + .. cmdv:: Search @string%@key + + The string string must be a notation or the main + symbol of a notation which is then interpreted in the scope bound to + the delimiting key :n:`@key` (see Section :ref:`LocalInterpretationRulesForNotations`). + + .. cmdv:: Search @term_pattern + + This searches for all statements or types of + definition that contains a subterm that matches the pattern + :token:`term_pattern` (holes of the pattern are either denoted by `_` or by + :n:`?@ident` when non linear patterns are expected). + + .. cmdv:: Search { + [-]@term_pattern_string } + + where + :n:`@term_pattern_string` is a term_pattern, a string, or a string followed + by a scope delimiting key `%key`. This generalization of ``Search`` searches + for all objects whose statement or type contains a subterm matching + :n:`@term_pattern` (or :n:`@qualid` if :n:`@string` is the notation for a reference + qualid) and whose name contains all string of the request that + correspond to valid identifiers. If a term_pattern or a string is + prefixed by `-`, the search excludes the objects that mention that + term_pattern or that string. + + .. cmdv:: Search @term_pattern_string … @term_pattern_string inside {+ @qualid } + + This restricts the search to constructions defined in the modules + named by the given :n:`qualid` sequence. + + .. cmdv:: Search @term_pattern_string … @term_pattern_string outside {+ @qualid } + + This restricts the search to constructions not defined in the modules + named by the given :n:`qualid` sequence. + + .. cmdv:: @selector: Search [-]@term_pattern_string … [-]@term_pattern_string + + This specifies the goal on which to search hypothesis (see + Section :ref:`invocation-of-tactics`). + By default the 1st goal is searched. This variant can + be combined with other variants presented here. + + .. example:: + + .. coqtop:: in + + Require Import ZArith. + + .. coqtop:: all + + Search Z.mul Z.add "distr". + + Search "+"%Z "*"%Z "distr" -positive -Prop. + + Search (?x * _ + ?x * _)%Z outside OmegaLemmas. + + .. cmdv:: SearchAbout + :name: SearchAbout + + .. deprecated:: 8.5 + + Up to |Coq| version 8.4, :cmd:`Search` had the behavior of current + :cmd:`SearchHead` and the behavior of current :cmd:`Search` was obtained with + command :cmd:`SearchAbout`. For compatibility, the deprecated name + :cmd:`SearchAbout` can still be used as a synonym of :cmd:`Search`. For + compatibility, the list of objects to search when using :cmd:`SearchAbout` + may also be enclosed by optional ``[ ]`` delimiters. + + +.. cmd:: SearchHead @term + + This command displays the name and type of all hypothesis of the + current goal (if any) and theorems of the current context whose + statement’s conclusion has the form `(term t1 .. tn)`. This command is + useful to remind the user of the name of library lemmas. + + .. example:: + + .. coqtop:: reset all + + SearchHead le. + + SearchHead (@eq bool). + + .. cmdv:: SearchHead @term inside {+ @qualid } + + This restricts the search to constructions defined in the modules named + by the given :n:`qualid` sequence. + + .. cmdv:: SearchHead term outside {+ @qualid } + + This restricts the search to constructions not defined in the modules + named by the given :n:`qualid` sequence. + + .. exn:: Module/section @qualid not found. + + No module :n:`@qualid` has been required (see Section :ref:`compiled-files`). + + .. cmdv:: @selector: SearchHead @term + + This specifies the goal on which to + search hypothesis (see Section :ref:`invocation-of-tactics`). + By default the 1st goal is searched. This variant can be combined + with other variants presented here. + + .. note:: Up to |Coq| version 8.4, ``SearchHead`` was named ``Search``. + + +.. cmd:: SearchPattern @term + + This command displays the name and type of all hypothesis of the + current goal (if any) and theorems of the current context whose + statement’s conclusion or last hypothesis and conclusion matches the + expressionterm where holes in the latter are denoted by `_`. + It is a variant of :n:`Search @term_pattern` that does not look for subterms + but searches for statements whose conclusion has exactly the expected + form, or whose statement finishes by the given series of + hypothesis/conclusion. + + .. example:: + + .. coqtop:: in + + Require Import Arith. + + .. coqtop:: all + + SearchPattern (_ + _ = _ + _). + + SearchPattern (nat -> bool). + + SearchPattern (forall l : list _, _ l l). + + Patterns need not be linear: you can express that the same expression + must occur in two places by using pattern variables `?ident`. + + + .. example:: + + .. coqtop:: all + + SearchPattern (?X1 + _ = _ + ?X1). + + .. cmdv:: SearchPattern @term inside {+ @qualid } + + This restricts the search to constructions defined in the modules + named by the given :n:`qualid` sequence. + + .. cmdv:: SearchPattern @term outside {+ @qualid } + + This restricts the search to constructions not defined in the modules + named by the given :n:`qualid` sequence. + + .. cmdv:: @selector: SearchPattern @term + + This specifies the goal on which to + search hypothesis (see Section :ref:`invocation-of-tactics`). + By default the 1st goal is + searched. This variant can be combined with other variants presented + here. + + +.. cmd:: SearchRewrite @term + + This command displays the name and type of all hypothesis of the + current goal (if any) and theorems of the current context whose + statement’s conclusion is an equality of which one side matches the + expression term. Holes in term are denoted by “_”. + + .. example:: + + .. coqtop:: in + + Require Import Arith. + + .. coqtop:: all + + SearchRewrite (_ + _ + _). + + .. cmdv:: SearchRewrite term inside {+ @qualid } + + This restricts the search to constructions defined in the modules + named by the given :n:`qualid` sequence. + + .. cmdv:: SearchRewrite @term outside {+ @qualid } + + This restricts the search to constructions not defined in the modules + named by the given :n:`qualid` sequence. + + .. cmdv:: @selector: SearchRewrite @term + + This specifies the goal on which to + search hypothesis (see Section :ref:`invocation-of-tactics`). + By default the 1st goal is + searched. This variant can be combined with other variants presented + here. + +.. note:: + + .. table:: Search Blacklist @string + :name: Search Blacklist + + Specifies a set of strings used to exclude lemmas from the results of :cmd:`Search`, + :cmd:`SearchHead`, :cmd:`SearchPattern` and :cmd:`SearchRewrite` queries. A lemma whose + fully-qualified name contains any of the strings will be excluded from the + search results. The default blacklisted substrings are ``_subterm``, ``_subproof`` and + ``Private_``. + + Use the :cmd:`Add @table` and :cmd:`Remove @table` commands to update the set of + blacklisted strings. + +.. cmd:: Locate @qualid + + This command displays the full name of objects whose name is a prefix + of the qualified identifier :n:`@qualid`, and consequently the |Coq| module in + which they are defined. It searches for objects from the different + qualified namespaces of |Coq|: terms, modules, Ltac, etc. + + .. example:: + + .. coqtop:: all + + Locate nat. + + Locate Datatypes.O. + + Locate Init.Datatypes.O. + + Locate Coq.Init.Datatypes.O. + + Locate I.Dont.Exist. + + .. cmdv:: Locate Term @qualid + + As Locate but restricted to terms. + + .. cmdv:: Locate Module @qualid + + As Locate but restricted to modules. + + .. cmdv:: Locate Ltac @qualid + + As Locate but restricted to tactics. + +.. seealso:: Section :ref:`locating-notations` + +.. _printing-flags: + +Printing flags +------------------------------- + +.. flag:: Fast Name Printing + + When turned on, |Coq| uses an asymptotically faster algorithm for the + generation of unambiguous names of bound variables while printing terms. + While faster, it is also less clever and results in a typically less elegant + display, e.g. it will generate more names rather than reusing certain names + across subterms. This flag is not enabled by default, because as Ltac + observes bound names, turning it on can break existing proof scripts. + + +.. _loading-files: + +Loading files +----------------- + +|Coq| offers the possibility of loading different parts of a whole +development stored in separate files. Their contents will be loaded as +if they were entered from the keyboard. This means that the loaded +files are ASCII files containing sequences of commands for |Coq|’s +toplevel. This kind of file is called a *script* for |Coq|. The standard +(and default) extension of |Coq|’s script files is .v. + + +.. cmd:: Load @ident + + This command loads the file named :n:`ident`.v, searching successively in + each of the directories specified in the *loadpath*. (see Section + :ref:`libraries-and-filesystem`) + + Files loaded this way cannot leave proofs open, and the ``Load`` + command cannot be used inside a proof either. + + .. cmdv:: Load @string + + Loads the file denoted by the string :n:`@string`, where + string is any complete filename. Then the `~` and .. abbreviations are + allowed as well as shell variables. If no extension is specified, |Coq| + will use the default extension ``.v``. + + .. cmdv:: Load Verbose @ident + Load Verbose @string + + Display, while loading, + the answers of |Coq| to each command (including tactics) contained in + the loaded file. + + .. seealso:: Section :ref:`controlling-display`. + + .. exn:: Can’t find file @ident on loadpath. + :undocumented: + + .. exn:: Load is not supported inside proofs. + :undocumented: + + .. exn:: Files processed by Load cannot leave open proofs. + :undocumented: + +.. _compiled-files: + +Compiled files +------------------ + +This section describes the commands used to load compiled files (see +Chapter :ref:`thecoqcommands` for documentation on how to compile a file). A compiled +file is a particular case of module called *library file*. + + +.. cmd:: Require @qualid + + This command looks in the loadpath for a file containing module :n:`@qualid` + and adds the corresponding module to the environment of |Coq|. As + library files have dependencies in other library files, the command + :cmd:`Require` :n:`@qualid` recursively requires all library files the module + qualid depends on and adds the corresponding modules to the + environment of |Coq| too. |Coq| assumes that the compiled files have been + produced by a valid |Coq| compiler and their contents are then not + replayed nor rechecked. + + To locate the file in the file system, :n:`@qualid` is decomposed under the + form :n:`dirpath.@ident` and the file :n:`@ident.vo` is searched in the physical + directory of the file system that is mapped in |Coq| loadpath to the + logical path dirpath (see Section :ref:`libraries-and-filesystem`). The mapping between + physical directories and logical names at the time of requiring the + file must be consistent with the mapping used to compile the file. If + several files match, one of them is picked in an unspecified fashion. + + + .. cmdv:: Require Import @qualid + :name: Require Import + + This loads and declares the module :n:`@qualid` + and its dependencies then imports the contents of :n:`@qualid` as described + :ref:`here <import_qualid>`. It does not import the modules on which + qualid depends unless these modules were themselves required in module + :n:`@qualid` + using :cmd:`Require Export`, as described below, or recursively required + through a sequence of :cmd:`Require Export`. If the module required has + already been loaded, :cmd:`Require Import` :n:`@qualid` simply imports it, as + :cmd:`Import` :n:`@qualid` would. + + .. cmdv:: Require Export @qualid + :name: Require Export + + This command acts as :cmd:`Require Import` :n:`@qualid`, + but if a further module, say `A`, contains a command :cmd:`Require Export` `B`, + then the command :cmd:`Require Import` `A` also imports the module `B.` + + .. cmdv:: Require [Import | Export] {+ @qualid } + + This loads the + modules named by the :token:`qualid` sequence and their recursive + dependencies. If + ``Import`` or ``Export`` is given, it also imports these modules and + all the recursive dependencies that were marked or transitively marked + as ``Export``. + + .. cmdv:: From @dirpath Require @qualid + + This command acts as :cmd:`Require`, but picks + any library whose absolute name is of the form :n:`@dirpath.@dirpath’.@qualid` + for some :n:`@dirpath’`. This is useful to ensure that the :token:`qualid` library + comes from a given package by making explicit its absolute root. + + .. exn:: Cannot load qualid: no physical path bound to dirpath. + :undocumented: + + .. exn:: Cannot find library foo in loadpath. + + The command did not find the + file foo.vo. Either foo.v exists but is not compiled or foo.vo is in a + directory which is not in your LoadPath (see Section :ref:`libraries-and-filesystem`). + + .. exn:: Compiled library @ident.vo makes inconsistent assumptions over library qualid. + + The command tried to load library file :n:`@ident`.vo that + depends on some specific version of library :n:`@qualid` which is not the + one already loaded in the current |Coq| session. Probably :n:`@ident.v` was + not properly recompiled with the last version of the file containing + module :token:`qualid`. + + .. exn:: Bad magic number. + + The file :n:`@ident.vo` was found but either it is not a + |Coq| compiled module, or it was compiled with an incompatible + version of |Coq|. + + .. exn:: The file :n:`@ident.vo` contains library dirpath and not library dirpath’. + + The library file :n:`@dirpath’` is indirectly required by the + ``Require`` command but it is bound in the current loadpath to the + file :n:`@ident.vo` which was bound to a different library name :token:`dirpath` at + the time it was compiled. + + + .. exn:: Require is not allowed inside a module or a module type. + + This command + is not allowed inside a module or a module type being defined. It is + meant to describe a dependency between compilation units. Note however + that the commands ``Import`` and ``Export`` alone can be used inside modules + (see Section :ref:`Import <import_qualid>`). + + .. seealso:: Chapter :ref:`thecoqcommands` + +.. cmd:: Print Libraries + + This command displays the list of library files loaded in the + current |Coq| session. For each of these libraries, it also tells if it + is imported. + + +.. cmd:: Declare ML Module {+ @string } + + This commands loads the OCaml compiled files + with names given by the :token:`string` sequence + (dynamic link). It is mainly used to load tactics dynamically. The + files are searched into the current OCaml loadpath (see the + command :cmd:`Add ML Path`). + Loading of OCaml files is only possible under the bytecode version of + ``coqtop`` (i.e. ``coqtop`` called with option ``-byte``, see chapter + :ref:`thecoqcommands`), or when |Coq| has been compiled with a + version of OCaml that supports native Dynlink (≥ 3.11). + + .. cmdv:: Local Declare ML Module {+ @string } + + This variant is not exported to the modules that import the module + where they occur, even if outside a section. + + .. exn:: File not found on loadpath: @string. + :undocumented: + + .. exn:: Loading of ML object file forbidden in a native Coq. + :undocumented: + + +.. cmd:: Print ML Modules + + This prints the name of all OCaml modules loaded with :cmd:`Declare ML Module`. + To know from where these module were loaded, the user + should use the command :cmd:`Locate File`. + + +.. _loadpath: + +Loadpath +------------ + +Loadpaths are preferably managed using |Coq| command line options (see +Section `libraries-and-filesystem`) but there remain vernacular commands to manage them +for practical purposes. Such commands are only meant to be issued in +the toplevel, and using them in source files is discouraged. + + +.. cmd:: Pwd + + This command displays the current working directory. + + +.. cmd:: Cd @string + + This command changes the current directory according to :token:`string` which + can be any valid path. + + .. cmdv:: Cd + + Is equivalent to Pwd. + + +.. cmd:: Add LoadPath @string as @dirpath + + This command is equivalent to the command line option + :n:`-Q @string @dirpath`. It adds the physical directory string to the current + |Coq| loadpath and maps it to the logical directory dirpath. + + .. cmdv:: Add LoadPath @string + + Performs as :n:`Add LoadPath @string @dirpath` but + for the empty directory path. + + +.. cmd:: Add Rec LoadPath @string as @dirpath + + This command is equivalent to the command line option + :n:`-R @string @dirpath`. It adds the physical directory string and all its + subdirectories to the current |Coq| loadpath. + + .. cmdv:: Add Rec LoadPath @string + + Works as :n:`Add Rec LoadPath @string as @dirpath` but for the empty + logical directory path. + + +.. cmd:: Remove LoadPath @string + + This command removes the path :n:`@string` from the current |Coq| loadpath. + + +.. cmd:: Print LoadPath + + This command displays the current |Coq| loadpath. + + .. cmdv:: Print LoadPath @dirpath + + Works as :cmd:`Print LoadPath` but displays only + the paths that extend the :n:`@dirpath` prefix. + + +.. cmd:: Add ML Path @string + + This command adds the path :n:`@string` to the current OCaml + loadpath (see the command `Declare ML Module`` in Section :ref:`compiled-files`). + + +.. cmd:: Add Rec ML Path @string + + This command adds the directory :n:`@string` and all its subdirectories to + the current OCaml loadpath (see the command :cmd:`Declare ML Module`). + + +.. cmd:: Print ML Path @string + + This command displays the current OCaml loadpath. This + command makes sense only under the bytecode version of ``coqtop``, i.e. + using option ``-byte`` + (see the command Declare ML Module in Section :ref:`compiled-files`). + +.. _locate-file: + +.. cmd:: Locate File @string + + This command displays the location of file string in the current + loadpath. Typically, string is a ``.cmo`` or ``.vo`` or ``.v`` file. + + +.. cmd:: Locate Library @dirpath + + This command gives the status of the |Coq| module dirpath. It tells if + the module is loaded and if not searches in the load path for a module + of logical name :n:`@dirpath`. + + +.. _backtracking: + +Backtracking +---------------- + +The backtracking commands described in this section can only be used +interactively, they cannot be part of a vernacular file loaded via +``Load`` or compiled by ``coqc``. + + +.. cmd:: Reset @ident + + This command removes all the objects in the environment since :n:`@ident` + was introduced, including :n:`@ident`. :n:`@ident` may be the name of a defined or + declared object as well as the name of a section. One cannot reset + over the name of a module or of an object inside a module. + + .. exn:: @ident: no such entry. + :undocumented: + + .. cmdv:: Reset Initial + + Goes back to the initial state, just after the start + of the interactive session. + + +.. cmd:: Back + + This command undoes all the effects of the last vernacular command. + Commands read from a vernacular file via a :cmd:`Load` are considered as a + single command. Proof management commands are also handled by this + command (see Chapter :ref:`proofhandling`). For that, Back may have to undo more than + one command in order to reach a state where the proof management + information is available. For instance, when the last command is a + :cmd:`Qed`, the management information about the closed proof has been + discarded. In this case, :cmd:`Back` will then undo all the proof steps up to + the statement of this proof. + + .. cmdv:: Back @num + + Undo :n:`@num` vernacular commands. As for Back, some extra + commands may be undone in order to reach an adequate state. For + instance Back :n:`@num` will not re-enter a closed proof, but rather go just + before that proof. + + .. exn:: Invalid backtrack. + + The user wants to undo more commands than available in the history. + +.. cmd:: BackTo @num + + This command brings back the system to the state labeled :n:`@num`, + forgetting the effect of all commands executed after this state. The + state label is an integer which grows after each successful command. + It is displayed in the prompt when in -emacs mode. Just as :cmd:`Back` (see + above), the :cmd:`BackTo` command now handles proof states. For that, it may + have to undo some extra commands and end on a state :n:`@num′ ≤ @num` if + necessary. + + .. cmdv:: Backtrack @num @num @num + :name: Backtrack + + .. deprecated:: 8.4 + + :cmd:`Backtrack` is a *deprecated* form of + :cmd:`BackTo` which allows explicitly manipulating the proof environment. The + three numbers represent the following: + + + *first number* : State label to reach, as for :cmd:`BackTo`. + + *second number* : *Proof state number* to unbury once aborts have been done. + |Coq| will compute the number of :cmd:`Undo` to perform (see Chapter :ref:`proofhandling`). + + *third number* : Number of :cmd:`Abort` to perform, i.e. the number of currently + opened nested proofs that must be canceled (see Chapter :ref:`proofhandling`). + + .. exn:: Invalid backtrack. + + The destination state label is unknown. + + +.. _quitting-and-debugging: + +Quitting and debugging +-------------------------- + + +.. cmd:: Quit + + This command permits to quit |Coq|. + + +.. cmd:: Drop + + This is used mostly as a debug facility by |Coq|’s implementers and does + not concern the casual user. This command permits to leave |Coq| + temporarily and enter the OCaml toplevel. The OCaml + command: + + :: + + #use "include";; + + adds the right loadpaths and loads some toplevel printers for all + abstract types of |Coq|- section_path, identifiers, terms, judgments, …. + You can also use the file base_include instead, that loads only the + pretty-printers for section_paths and identifiers. You can return back + to |Coq| with the command: + + :: + + go();; + + .. warning:: + + #. It only works with the bytecode version of |Coq| (i.e. `coqtop.byte`, + see Section `interactive-use`). + #. You must have compiled |Coq| from the source package and set the + environment variable COQTOP to the root of your copy of the sources + (see Section `customization-by-environment-variables`). + + +.. TODO : command is not a syntax entry + +.. cmd:: Time @command + + This command executes the vernacular command :n:`@command` and displays the + time needed to execute it. + + +.. cmd:: Redirect @string @command + + This command executes the vernacular command :n:`@command`, redirecting its + output to ":n:`@string`.out". + + +.. cmd:: Timeout @num @command + + This command executes the vernacular command :n:`@command`. If the command + has not terminated after the time specified by the :n:`@num` (time + expressed in seconds), then it is interrupted and an error message is + displayed. + + .. opt:: Default Timeout @num + :name: Default Timeout + + This option controls a default timeout for subsequent commands, as if they + were passed to a :cmd:`Timeout` command. Commands already starting by a + :cmd:`Timeout` are unaffected. + + +.. cmd:: Fail @command + + For debugging scripts, sometimes it is desirable to know + whether a command or a tactic fails. If the given :n:`@command` + fails, the ``Fail`` statement succeeds, without changing the proof + state, and in interactive mode, the system + prints a message confirming the failure. + If the given :n:`@command` succeeds, the statement is an error, and + it prints a message indicating that the failure did not occur. + + .. exn:: The command has not failed! + :undocumented: + + +.. _controlling-display: + +Controlling display +----------------------- + +.. flag:: Silent + + This option controls the normal displaying. + +.. opt:: Warnings "{+, {? %( - %| + %) } @ident }" + :name: Warnings + + This option configures the display of warnings. It is experimental, and + expects, between quotes, a comma-separated list of warning names or + categories. Adding - in front of a warning or category disables it, adding + + makes it an error. It is possible to use the special categories all and + default, the latter containing the warnings enabled by default. The flags are + interpreted from left to right, so in case of an overlap, the flags on the + right have higher priority, meaning that `A,-A` is equivalent to `-A`. + +.. flag:: Search Output Name Only + + This option restricts the output of search commands to identifier names; + turning it on causes invocations of :cmd:`Search`, :cmd:`SearchHead`, + :cmd:`SearchPattern`, :cmd:`SearchRewrite` etc. to omit types from their + output, printing only identifiers. + +.. opt:: Printing Width @num + :name: Printing Width + + This command sets which left-aligned part of the width of the screen is used + for display. At the time of writing this documentation, the default value + is 78. + +.. opt:: Printing Depth @num + :name: Printing Depth + + This option controls the nesting depth of the formatter used for pretty- + printing. Beyond this depth, display of subterms is replaced by dots. At the + time of writing this documentation, the default value is 50. + +.. flag:: Printing Compact Contexts + + This option controls the compact display mode for goals contexts. When on, + the printer tries to reduce the vertical size of goals contexts by putting + several variables (even if of different types) on the same line provided it + does not exceed the printing width (see :opt:`Printing Width`). At the time + of writing this documentation, it is off by default. + +.. flag:: Printing Unfocused + + This option controls whether unfocused goals are displayed. Such goals are + created by focusing other goals with bullets (see :ref:`bullets` or + :ref:`curly braces <curly-braces>`). It is off by default. + +.. flag:: Printing Dependent Evars Line + + This option controls the printing of the “(dependent evars: …)” line when + ``-emacs`` is passed. + + +.. _vernac-controlling-the-reduction-strategies: + +Controlling the reduction strategies and the conversion algorithm +---------------------------------------------------------------------- + + +|Coq| provides reduction strategies that the tactics can invoke and two +different algorithms to check the convertibility of types. The first +conversion algorithm lazily compares applicative terms while the other +is a brute-force but efficient algorithm that first normalizes the +terms before comparing them. The second algorithm is based on a +bytecode representation of terms similar to the bytecode +representation used in the ZINC virtual machine :cite:`Leroy90`. It is +especially useful for intensive computation of algebraic values, such +as numbers, and for reflection-based tactics. The commands to fine- +tune the reduction strategies and the lazy conversion algorithm are +described first. + +.. cmd:: Opaque {+ @qualid } + + This command has an effect on unfoldable constants, i.e. on constants + defined by :cmd:`Definition` or :cmd:`Let` (with an explicit body), or by a command + assimilated to a definition such as :cmd:`Fixpoint`, :cmd:`Program Definition`, etc, + or by a proof ended by :cmd:`Defined`. The command tells not to unfold the + constants in the :n:`@qualid` sequence in tactics using δ-conversion (unfolding + a constant is replacing it by its definition). + + :cmd:`Opaque` has also an effect on the conversion algorithm of |Coq|, telling + it to delay the unfolding of a constant as much as possible when |Coq| + has to check the conversion (see Section :ref:`conversion-rules`) of two distinct + applied constants. + + .. cmdv:: Global Opaque {+ @qualid } + :name: Global Opaque + + The scope of :cmd:`Opaque` is limited to the current section, or current + file, unless the variant :cmd:`Global Opaque` is used. + + .. seealso:: + + Sections :ref:`performingcomputations`, :ref:`tactics-automating`, + :ref:`proof-editing-mode` + + .. exn:: The reference @qualid was not found in the current environment. + + There is no constant referred by :n:`@qualid` in the environment. + Nevertheless, if you asked :cmd:`Opaque` `foo` `bar` and if `bar` does + not exist, `foo` is set opaque. + +.. cmd:: Transparent {+ @qualid } + + This command is the converse of :cmd:`Opaque` and it applies on unfoldable + constants to restore their unfoldability after an Opaque command. + + Note in particular that constants defined by a proof ended by Qed are + not unfoldable and Transparent has no effect on them. This is to keep + with the usual mathematical practice of *proof irrelevance*: what + matters in a mathematical development is the sequence of lemma + statements, not their actual proofs. This distinguishes lemmas from + the usual defined constants, whose actual values are of course + relevant in general. + + .. cmdv:: Global Transparent {+ @qualid } + :name: Global Transparent + + The scope of Transparent is limited to the current section, or current + file, unless the variant :cmd:`Global Transparent` is + used. + + .. exn:: The reference @qualid was not found in the current environment. + + There is no constant referred by :n:`@qualid` in the environment. + + .. seealso:: + + Sections :ref:`performingcomputations`, + :ref:`tactics-automating`, :ref:`proof-editing-mode` + +.. _vernac-strategy: + +.. cmd:: Strategy @level [ {+ @qualid } ] + + This command generalizes the behavior of Opaque and Transparent + commands. It is used to fine-tune the strategy for unfolding + constants, both at the tactic level and at the kernel level. This + command associates a level to the qualified names in the :n:`@qualid` + sequence. Whenever two + expressions with two distinct head constants are compared (for + instance, this comparison can be triggered by a type cast), the one + with lower level is expanded first. In case of a tie, the second one + (appearing in the cast type) is expanded. + + Levels can be one of the following (higher to lower): + + + ``opaque`` : level of opaque constants. They cannot be expanded by + tactics (behaves like +∞, see next item). + + :n:`@num` : levels indexed by an integer. Level 0 corresponds to the + default behavior, which corresponds to transparent constants. This + level can also be referred to as transparent. Negative levels + correspond to constants to be expanded before normal transparent + constants, while positive levels correspond to constants to be + expanded after normal transparent constants. + + ``expand`` : level of constants that should be expanded first (behaves + like −∞) + + .. cmdv:: Local Strategy @level [ {+ @qualid } ] + + These directives survive section and module closure, unless the + command is prefixed by ``Local``. In the latter case, the behavior + regarding sections and modules is the same as for the :cmd:`Transparent` and + :cmd:`Opaque` commands. + + +.. cmd:: Print Strategy @qualid + + This command prints the strategy currently associated to :n:`@qualid`. It + fails if :n:`@qualid` is not an unfoldable reference, that is, neither a + variable nor a constant. + + .. exn:: The reference is not unfoldable. + :undocumented: + + .. cmdv:: Print Strategies + + Print all the currently non-transparent strategies. + + +.. cmd:: Declare Reduction @ident := @convtactic + + This command allows giving a short name to a reduction expression, for + instance lazy beta delta [foo bar]. This short name can then be used + in :n:`Eval @ident in` or ``eval`` directives. This command + accepts the + Local modifier, for discarding this reduction name at the end of the + file or module. For the moment the name cannot be qualified. In + particular declaring the same name in several modules or in several + functor applications will be refused if these declarations are not + local. The name :n:`@ident` cannot be used directly as an Ltac tactic, but + nothing prevents the user to also perform a + :n:`Ltac @ident := @convtactic`. + + .. seealso:: :ref:`performingcomputations` + + +.. _controlling-locality-of-commands: + +Controlling the locality of commands +----------------------------------------- + + +.. cmd:: Local @command + Global @command + + Some commands support a Local or Global prefix modifier to control the + scope of their effect. There are four kinds of commands: + + + + Commands whose default is to extend their effect both outside the + section and the module or library file they occur in. For these + commands, the Local modifier limits the effect of the command to the + current section or module it occurs in. As an example, the :cmd:`Coercion` + and :cmd:`Strategy` commands belong to this category. + + Commands whose default behavior is to stop their effect at the end + of the section they occur in but to extend their effect outside the module or + library file they occur in. For these commands, the Local modifier limits the + effect of the command to the current module if the command does not occur in a + section and the Global modifier extends the effect outside the current + sections and current module if the command occurs in a section. As an example, + the :cmd:`Arguments`, :cmd:`Ltac` or :cmd:`Notation` commands belong + to this category. Notice that a subclass of these commands do not support + extension of their scope outside sections at all and the Global modifier is not + applicable to them. + + Commands whose default behavior is to stop their effect at the end + of the section or module they occur in. For these commands, the ``Global`` + modifier extends their effect outside the sections and modules they + occur in. The :cmd:`Transparent` and :cmd:`Opaque` + (see Section :ref:`vernac-controlling-the-reduction-strategies`) commands + belong to this category. + + Commands whose default behavior is to extend their effect outside + sections but not outside modules when they occur in a section and to + extend their effect outside the module or library file they occur in + when no section contains them.For these commands, the Local modifier + limits the effect to the current section or module while the Global + modifier extends the effect outside the module even when the command + occurs in a section. The :cmd:`Set` and :cmd:`Unset` commands belong to this + category. + +.. _internal-registration-commands: + +Internal registration commands +-------------------------------- + +Due to their internal nature, the commands that are presented in this section +are not for general use. They are meant to appear only in standard libraries and +in support libraries of plug-ins. + +.. _exposing-constants-to-ocaml-libraries: + +Exposing constants to OCaml libraries +```````````````````````````````````````````````````````````````` + +.. cmd:: Register @qualid__1 as @qualid__2 + + This command exposes the constant :n:`@qualid__1` to OCaml libraries under + the name :n:`@qualid__2`. This constant can then be dynamically located + calling :n:`Coqlib.lib_ref "@qualid__2"`; i.e., there is no need to known + where is the constant defined (file, module, library, etc.). + + As a special case, when the first segment of :n:`@qualid__2` is :g:`kernel`, + the constant is exposed to the kernel. For instance, the `Int63` module + features the following declaration: + + .. coqdoc:: + + Register bool as kernel.ind_bool. + + This makes the kernel aware of what is the type of boolean values. This + information is used for instance to define the return type of the + :g:`#int63_eq` primitive. + + .. seealso:: :ref:`primitive-integers` + +Inlining hints for the fast reduction machines +```````````````````````````````````````````````````````````````` + +.. cmd:: Register Inline @qualid + + This command gives as a hint to the reduction machines (VM and native) that + the body of the constant :n:`@qualid` should be inlined in the generated code. + +Registering primitive operations +```````````````````````````````` + +.. cmd:: Primitive @ident__1 := #@ident__2. + + Declares :n:`@ident__1` as the primitive operator :n:`#@ident__2`. When + running this command, the type of the primitive should be already known by + the kernel (this is achieved through this command for primitive types and + through the :cmd:`Register` command with the :g:`kernel` name-space for other + types). diff --git a/doc/sphinx/refman-preamble.rst b/doc/sphinx/refman-preamble.rst new file mode 100644 index 0000000000..c662028773 --- /dev/null +++ b/doc/sphinx/refman-preamble.rst @@ -0,0 +1,98 @@ +.. This file is automatically prepended to all other files using the ``rst_prolog`` option. + +.. only:: html + + .. This is included once per page in the HTML build, and a single time (in the + document's preamble) in the LaTeX one. + + .. preamble:: /refman-preamble.sty + +.. Some handy replacements for common items + +.. role:: smallcaps + +.. |A_1| replace:: `A`\ :math:`_{1}` +.. |A_n| replace:: `A`\ :math:`_{n}` +.. |arg_1| replace:: `arg`\ :math:`_{1}` +.. |arg_n| replace:: `arg`\ :math:`_{n}` +.. |bdi| replace:: :math:`\beta\delta\iota` +.. |binder_1| replace:: `binder`\ :math:`_{1}` +.. |binder_n| replace:: `binder`\ :math:`_{n}` +.. |binders_1| replace:: `binders`\ :math:`_{1}` +.. |binders_n| replace:: `binders`\ :math:`_{n}` +.. |C_1| replace:: `C`\ :math:`_{1}` +.. |c_1| replace:: `c`\ :math:`_{1}` +.. |C_2| replace:: `C`\ :math:`_{2}` +.. |c_i| replace:: `c`\ :math:`_{i}` +.. |c_n| replace:: `c`\ :math:`_{n}` +.. |Cic| replace:: :smallcaps:`Cic` +.. |class_1| replace:: `class`\ :math:`_{1}` +.. |class_2| replace:: `class`\ :math:`_{2}` +.. |Coq| replace:: :smallcaps:`Coq` +.. |CoqIDE| replace:: :smallcaps:`CoqIDE` +.. |eq_beta_delta_iota_zeta| replace:: `=`\ :math:`_{\beta\delta\iota\zeta}` +.. |Gallina| replace:: :smallcaps:`Gallina` +.. |ident_0| replace:: `ident`\ :math:`_{0}` +.. |ident_1,1| replace:: `ident`\ :math:`_{1,1}` +.. |ident_1,k_1| replace:: `ident`\ :math:`_{1,k_1}`) +.. |ident_1| replace:: `ident`\ :math:`_{1}` +.. |ident_2| replace:: `ident`\ :math:`_{2}` +.. |ident_3| replace:: `ident`\ :math:`_{3}` +.. |ident_i| replace:: `ident`\ :math:`_{i}` +.. |ident_j| replace:: `ident`\ :math:`_{j}` +.. |ident_k| replace:: `ident`\ :math:`_{k}` +.. |ident_n,1| replace:: `ident`\ :math:`_{n,1}` +.. |ident_n,k_n| replace:: `ident`\ :math:`_{n,k_n}` +.. |ident_n| replace:: `ident`\ :math:`_{n}` +.. |Latex| replace:: :smallcaps:`LaTeX` +.. |L_tac| replace:: `L`:sub:`tac` +.. |Ltac| replace:: `L`:sub:`tac` +.. |ML| replace:: :smallcaps:`ML` +.. |mod_0| replace:: `mod`\ :math:`_{0}` +.. |mod_1| replace:: `mod`\ :math:`_{1}` +.. |mod_2| replace:: `mod`\ :math:`_{1}` +.. |mod_n| replace:: `mod`\ :math:`_{n}` +.. |module_0| replace:: `module`\ :math:`_{0}` +.. |module_1| replace:: `module`\ :math:`_{1}` +.. |module_expression_0| replace:: `module_expression`\ :math:`_{0}` +.. |module_expression_1| replace:: `module_expression`\ :math:`_{1}` +.. |module_expression_i| replace:: `module_expression`\ :math:`_{i}` +.. |module_expression_n| replace:: `module_expression`\ :math:`_{n}` +.. |module_n| replace:: `module`\ :math:`_{n}` +.. |module_type_0| replace:: `module_type`\ :math:`_{0}` +.. |module_type_1| replace:: `module_type`\ :math:`_{1}` +.. |module_type_i| replace:: `module_type`\ :math:`_{i}` +.. |module_type_n| replace:: `module_type`\ :math:`_{n}` +.. |N| replace:: ``N`` +.. |nat| replace:: ``nat`` +.. |OCaml| replace:: :smallcaps:`OCaml` +.. |p_1| replace:: `p`\ :math:`_{1}` +.. |p_i| replace:: `p`\ :math:`_{i}` +.. |p_n| replace:: `p`\ :math:`_{n}` +.. |Program| replace:: :strong:`Program` +.. |SSR| replace:: :smallcaps:`SSReflect` +.. |t_1| replace:: `t`\ :math:`_{1}` +.. |t_i| replace:: `t`\ :math:`_{i}` +.. |t_m| replace:: `t`\ :math:`_{m}` +.. |t_n| replace:: `t`\ :math:`_{n}` +.. |f_1| replace:: `f`\ :math:`_{1}` +.. |f_i| replace:: `f`\ :math:`_{i}` +.. |f_m| replace:: `f`\ :math:`_{m}` +.. |f_n| replace:: `f`\ :math:`_{n}` +.. |u_1| replace:: `u`\ :math:`_{1}` +.. |u_i| replace:: `u`\ :math:`_{i}` +.. |u_m| replace:: `u`\ :math:`_{m}` +.. |u_n| replace:: `u`\ :math:`_{n}` +.. |term_0| replace:: `term`\ :math:`_{0}` +.. |term_1| replace:: `term`\ :math:`_{1}` +.. |term_2| replace:: `term`\ :math:`_{2}` +.. |term_n| replace:: `term`\ :math:`_{n}` +.. |type_0| replace:: `type`\ :math:`_{0}` +.. |type_1| replace:: `type`\ :math:`_{1}` +.. |type_2| replace:: `type`\ :math:`_{2}` +.. |type_3| replace:: `type`\ :math:`_{3}` +.. |type_n| replace:: `type`\ :math:`_{n}` +.. |x_1| replace:: `x`\ :math:`_{1}` +.. |x_i| replace:: `x`\ :math:`_{i}` +.. |x_n| replace:: `x`\ :math:`_{n}` +.. |Z| replace:: ``Z`` diff --git a/doc/sphinx/refman-preamble.sty b/doc/sphinx/refman-preamble.sty new file mode 100644 index 0000000000..90a63a5a2d --- /dev/null +++ b/doc/sphinx/refman-preamble.sty @@ -0,0 +1,91 @@ +\newcommand{\alors}{\textsf{then}} +\newcommand{\alter}{\textsf{alter}} +\newcommand{\as}{\kw{as}} +\newcommand{\Assum}[3]{\kw{Assum}(#1)(#2:#3)} +\newcommand{\bool}{\textsf{bool}} +\newcommand{\case}{\kw{case}} +\newcommand{\conc}{\textsf{conc}} +\newcommand{\cons}{\textsf{cons}} +\newcommand{\consf}{\textsf{consf}} +\newcommand{\conshl}{\textsf{cons\_hl}} +\newcommand{\Def}[4]{\kw{Def}(#1)(#2:=#3:#4)} +\newcommand{\emptyf}{\textsf{emptyf}} +\newcommand{\End}{\kw{End}} +\newcommand{\kwend}{\kw{end}} +\newcommand{\EqSt}{\textsf{EqSt}} +\newcommand{\even}{\textsf{even}} +\newcommand{\evenO}{\textsf{even}_\textsf{O}} +\newcommand{\evenS}{\textsf{even}_\textsf{S}} +\newcommand{\false}{\textsf{false}} +\newcommand{\filter}{\textsf{filter}} +\newcommand{\Fix}{\kw{Fix}} +\newcommand{\fix}{\kw{fix}} +\newcommand{\for}{\textsf{for}} +\newcommand{\forest}{\textsf{forest}} +\newcommand{\from}{\textsf{from}} +\newcommand{\Functor}{\kw{Functor}} +\newcommand{\haslength}{\textsf{has\_length}} +\newcommand{\hd}{\textsf{hd}} +\newcommand{\ident}{\textsf{ident}} +\newcommand{\In}{\kw{in}} +\newcommand{\Ind}[4]{\kw{Ind}[#2](#3:=#4)} +\newcommand{\ind}[3]{\kw{Ind}~[#1]\left(#2\mathrm{~:=~}#3\right)} +\newcommand{\Indp}[5]{\kw{Ind}_{#5}(#1)[#2](#3:=#4)} +\newcommand{\Indpstr}[6]{\kw{Ind}_{#5}(#1)[#2](#3:=#4)/{#6}} +\newcommand{\injective}{\kw{injective}} +\newcommand{\kw}[1]{\textsf{#1}} +\newcommand{\lb}{\lambda} +\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{\ModA}[2]{{\kw{ModA}}({#1}=={#2})} +\newcommand{\ModS}[2]{{\kw{Mod}}({#1}:{#2})} +\newcommand{\ModType}[2]{{\kw{ModType}}({#1}:={#2})} +\newcommand{\mto}{.\;} +\newcommand{\Nat}{\mathbb{N}} +\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{\Prod}{\textsf{prod}} +\newcommand{\SProp}{\textsf{SProp}} +\newcommand{\Prop}{\textsf{Prop}} +\newcommand{\return}{\kw{return}} +\newcommand{\Set}{\textsf{Set}} +\newcommand{\si}{\textsf{if}} +\newcommand{\sinon}{\textsf{else}} +\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{\true}{\textsf{true}} +\newcommand{\Type}{\textsf{Type}} +\newcommand{\unfold}{\textsf{unfold}} +\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}]} +\newcommand{\zeros}{\textsf{zeros}} diff --git a/doc/sphinx/user-extensions/proof-schemes.rst b/doc/sphinx/user-extensions/proof-schemes.rst new file mode 100644 index 0000000000..418922e9b3 --- /dev/null +++ b/doc/sphinx/user-extensions/proof-schemes.rst @@ -0,0 +1,400 @@ +.. _proofschemes: + +Proof schemes +=============== + +.. _proofschemes-induction-principles: + +Generation of induction principles with ``Scheme`` +-------------------------------------------------------- + +The ``Scheme`` command is a high-level tool for generating automatically +(possibly mutual) induction principles for given types and sorts. Its +syntax follows the schema: + +.. cmd:: Scheme @ident__1 := Induction for @ident__2 Sort @sort {* with @ident__i := Induction for @ident__j Sort @sort} + + This command is a high-level tool for generating automatically + (possibly mutual) induction principles for given types and sorts. + Each :n:`@ident__j` is a different inductive type identifier belonging to + the same package of mutual inductive definitions. + The command generates the :n:`@ident__i`\s to be mutually recursive + definitions. Each term :n:`@ident__i` proves a general principle of mutual + induction for objects in type :n:`@ident__j`. + +.. cmdv:: Scheme @ident := Minimality for @ident Sort @sort {* with @ident := Minimality for @ident' Sort @sort} + + Same as before but defines a non-dependent elimination principle more + natural in case of inductively defined relations. + +.. cmdv:: Scheme Equality for @ident + :name: Scheme Equality + + Tries to generate a Boolean equality and a proof of the decidability of the usual equality. If `ident` + involves some other inductive types, their equality has to be defined first. + +.. cmdv:: Scheme Induction for @ident Sort @sort {* with Induction for @ident Sort @sort} + + If you do not provide the name of the schemes, they will be automatically computed from the + sorts involved (works also with Minimality). + +.. example:: + + Induction scheme for tree and forest. + + A mutual induction principle for tree and forest in sort ``Set`` can be defined using the command + + .. coqtop:: none + + Axiom A : Set. + Axiom B : Set. + + .. coqtop:: all + + Inductive tree : Set := node : A -> forest -> tree + with forest : Set := + leaf : B -> forest + | cons : tree -> forest -> forest. + + Scheme tree_forest_rec := Induction for tree Sort Set + with forest_tree_rec := Induction for forest Sort Set. + + You may now look at the type of tree_forest_rec: + + .. coqtop:: all + + Check tree_forest_rec. + + This principle involves two different predicates for trees andforests; + it also has three premises each one corresponding to a constructor of + one of the inductive definitions. + + The principle `forest_tree_rec` shares exactly the same premises, only + the conclusion now refers to the property of forests. + +.. example:: + + Predicates odd and even on naturals. + + Let odd and even be inductively defined as: + + .. coqtop:: all + + Inductive odd : nat -> Prop := oddS : forall n:nat, even n -> odd (S n) + with even : nat -> Prop := + | evenO : even 0 + | evenS : forall n:nat, odd n -> even (S n). + + The following command generates a powerful elimination principle: + + .. coqtop:: all + + Scheme odd_even := Minimality for odd Sort Prop + with even_odd := Minimality for even Sort Prop. + + The type of odd_even for instance will be: + + .. coqtop:: all + + Check odd_even. + + The type of `even_odd` shares the same premises but the conclusion is + `(n:nat)(even n)->(P0 n)`. + + +Automatic declaration of schemes +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. flag:: Elimination Schemes + + Enables automatic declaration of induction principles when defining a new + inductive type. Defaults to on. + +.. flag:: Nonrecursive Elimination Schemes + + Enables automatic declaration of induction principles for types declared with the :cmd:`Variant` and + :cmd:`Record` commands. Defaults to off. + +.. flag:: Case Analysis Schemes + + This flag governs the generation of case analysis lemmas for inductive types, + i.e. corresponding to the pattern matching term alone and without fixpoint. + +.. flag:: Boolean Equality Schemes + Decidable Equality Schemes + + These flags control the automatic declaration of those Boolean equalities (see + the second variant of ``Scheme``). + +.. warning:: + + You have to be careful with this option since Coq may now reject well-defined + inductive types because it cannot compute a Boolean equality for them. + +.. flag:: Rewriting Schemes + + This flag governs generation of equality-related schemes such as congruence. + +Combined Scheme +~~~~~~~~~~~~~~~~~~~~~~ + +.. cmd:: Combined Scheme @ident from {+, @ident__i} + + This command is a tool for combining induction principles generated + by the :cmd:`Scheme` command. + Each :n:`@ident__i` is a different inductive principle that must belong + to the same package of mutual inductive principle definitions. + This command generates :n:`@ident` to be the conjunction of the + principles: it is built from the common premises of the principles + and concluded by the conjunction of their conclusions. + In the case where all the inductive principles used are in sort + ``Prop``, the propositional conjunction ``and`` is used, otherwise + the simple product ``prod`` is used instead. + +.. example:: + + We can define the induction principles for trees and forests using: + + .. coqtop:: all + + Scheme tree_forest_ind := Induction for tree Sort Prop + with forest_tree_ind := Induction for forest Sort Prop. + + Then we can build the combined induction principle which gives the + conjunction of the conclusions of each individual principle: + + .. coqtop:: all + + Combined Scheme tree_forest_mutind from tree_forest_ind,forest_tree_ind. + + The type of tree_forest_mutind will be: + + .. coqtop:: all + + Check tree_forest_mutind. + +.. example:: + + We can also combine schemes at sort ``Type``: + + .. coqtop:: all + + Scheme tree_forest_rect := Induction for tree Sort Type + with forest_tree_rect := Induction for forest Sort Type. + + .. coqtop:: all + + Combined Scheme tree_forest_mutrect from tree_forest_rect, forest_tree_rect. + + .. coqtop:: all + + Check tree_forest_mutrect. + +.. _functional-scheme: + +Generation of induction principles with ``Functional`` ``Scheme`` +----------------------------------------------------------------- + + +.. cmd:: Functional Scheme @ident__0 := Induction for @ident' Sort @sort {* with @ident__i := Induction for @ident__i' Sort @sort} + + This command is a high-level experimental tool for + generating automatically induction principles corresponding to + (possibly mutually recursive) functions. First, it must be made + available via ``Require Import FunInd``. + Each :n:`@ident__i` is a different mutually defined function + name (the names must be in the same order as when they were defined). This + command generates the induction principle for each :n:`@ident__i`, following + the recursive structure and case analyses of the corresponding function + :n:`@ident__i'`. + +.. warning:: + + There is a difference between induction schemes generated by the command + :cmd:`Functional Scheme` and these generated by the :cmd:`Function`. Indeed, + :cmd:`Function` generally produces smaller principles that are closer to how + a user would implement them. See :ref:`advanced-recursive-functions` for details. + +.. example:: + + Induction scheme for div2. + + We define the function div2 as follows: + + .. coqtop:: all + + Require Import FunInd. + Require Import Arith. + + Fixpoint div2 (n:nat) : nat := + match n with + | O => 0 + | S O => 0 + | S (S n') => S (div2 n') + end. + + The definition of a principle of induction corresponding to the + recursive structure of `div2` is defined by the command: + + .. coqtop:: all + + Functional Scheme div2_ind := Induction for div2 Sort Prop. + + You may now look at the type of div2_ind: + + .. coqtop:: all + + Check div2_ind. + + We can now prove the following lemma using this principle: + + .. coqtop:: all + + Lemma div2_le' : forall n:nat, div2 n <= n. + intro n. + pattern n, (div2 n). + apply div2_ind; intros. + auto with arith. + auto with arith. + simpl; auto with arith. + Qed. + + We can use directly the functional induction (:tacn:`function induction`) tactic instead + of the pattern/apply trick: + + .. coqtop:: all + + Reset div2_le'. + + Lemma div2_le : forall n:nat, div2 n <= n. + intro n. + functional induction (div2 n). + auto with arith. + auto with arith. + auto with arith. + Qed. + +.. example:: + + Induction scheme for tree_size. + + We define trees by the following mutual inductive type: + + .. original LaTeX had "Variable" instead of "Axiom", which generates an ugly warning + + .. coqtop:: reset all + + Axiom A : Set. + + Inductive tree : Set := + node : A -> forest -> tree + with forest : Set := + | empty : forest + | cons : tree -> forest -> forest. + + We define the function tree_size that computes the size of a tree or a + forest. Note that we use ``Function`` which generally produces better + principles. + + .. coqtop:: all + + Require Import FunInd. + + Function tree_size (t:tree) : nat := + match t with + | node A f => S (forest_size f) + end + with forest_size (f:forest) : nat := + match f with + | empty => 0 + | cons t f' => (tree_size t + forest_size f') + end. + + Notice that the induction principles ``tree_size_ind`` and ``forest_size_ind`` + generated by ``Function`` are not mutual. + + .. coqtop:: all + + Check tree_size_ind. + + Mutual induction principles following the recursive structure of ``tree_size`` + and ``forest_size`` can be generated by the following command: + + .. coqtop:: all + + Functional Scheme tree_size_ind2 := Induction for tree_size Sort Prop + with forest_size_ind2 := Induction for forest_size Sort Prop. + + You may now look at the type of `tree_size_ind2`: + + .. coqtop:: all + + Check tree_size_ind2. + +.. _derive-inversion: + +Generation of inversion principles with ``Derive`` ``Inversion`` +----------------------------------------------------------------- + +.. cmd:: Derive Inversion @ident with forall (x : T), I t Sort sort + + This command generates an inversion principle for the + :tacn:`inversion ... using ...` tactic. Let :g:`I` be an inductive + predicate and :g:`x` the variables occurring in t. This command + generates and stocks the inversion lemma for the sort :g:`sort` + corresponding to the instance :g:`∀ (x:T), I t` with the name + :n:`@ident` in the global environment. When applied, it is + equivalent to having inverted the instance with the tactic + :g:`inversion`. + + +.. cmdv:: Derive Inversion_clear @ident with forall (x:T), I t Sort @sort + + When applied, it is equivalent to having inverted the instance with the + tactic inversion replaced by the tactic `inversion_clear`. + +.. cmdv:: Derive Dependent Inversion @ident with forall (x:T), I t Sort @sort + + When applied, it is equivalent to having inverted the instance with + the tactic `dependent inversion`. + +.. cmdv:: Derive Dependent Inversion_clear @ident with forall(x:T), I t Sort @sort + + When applied, it is equivalent to having inverted the instance + with the tactic `dependent inversion_clear`. + +.. example:: + + Consider the relation `Le` over natural numbers and the following + parameter ``P``: + + .. coqtop:: all + + Inductive Le : nat -> nat -> Set := + | LeO : forall n:nat, Le 0 n + | LeS : forall n m:nat, Le n m -> Le (S n) (S m). + + Parameter P : nat -> nat -> Prop. + + To generate the inversion lemma for the instance :g:`(Le (S n) m)` and the + sort :g:`Prop`, we do: + + .. coqtop:: all + + Derive Inversion_clear leminv with (forall n m:nat, Le (S n) m) Sort Prop. + Check leminv. + + Then we can use the proven inversion lemma: + + .. the original LaTeX did not have any Coq code to setup the goal + + .. coqtop:: none + + Goal forall (n m : nat) (H : Le (S n) m), P n m. + intros. + + .. coqtop:: all + + Show. + + inversion H using leminv. diff --git a/doc/sphinx/user-extensions/syntax-extensions.rst b/doc/sphinx/user-extensions/syntax-extensions.rst new file mode 100644 index 0000000000..63df3d37bf --- /dev/null +++ b/doc/sphinx/user-extensions/syntax-extensions.rst @@ -0,0 +1,1834 @@ +.. _syntaxextensionsandinterpretationscopes: + +Syntax extensions and interpretation scopes +======================================================== + +In this chapter, we introduce advanced commands to modify the way Coq +parses and prints objects, i.e. the translations between the concrete +and internal representations of terms and commands. + +The main commands to provide custom symbolic notations for terms are +:cmd:`Notation` and :cmd:`Infix`; they will be described in the +:ref:`next section <Notations>`. There is also a +variant of :cmd:`Notation` which does not modify the parser; this provides a +form of :ref:`abbreviation <Abbreviations>`. It is +sometimes expected that the same symbolic notation has different meanings in +different contexts; to achieve this form of overloading, |Coq| offers a notion +of :ref:`interpretation scopes <Scopes>`. +The main command to provide custom notations for tactics is :cmd:`Tactic Notation`. + +.. coqtop:: none + + Set Printing Depth 50. + +.. _Notations: + +Notations +--------- + +Basic notations +~~~~~~~~~~~~~~~ + +.. cmd:: Notation + + A *notation* is a symbolic expression denoting some term or term + pattern. + +A typical notation is the use of the infix symbol ``/\`` to denote the +logical conjunction (and). Such a notation is declared by + +.. coqtop:: in + + Notation "A /\ B" := (and A B). + +The expression :g:`(and A B)` is the abbreviated term and the string :g:`"A /\ B"` +(called a *notation*) tells how it is symbolically written. + +A notation is always surrounded by double quotes (except when the +abbreviation has the form of an ordinary applicative expression; +see :ref:`Abbreviations`). The notation is composed of *tokens* separated by +spaces. Identifiers in the string (such as ``A`` and ``B``) are the *parameters* +of the notation. Each of them must occur at least once in the denoted term. The +other elements of the string (such as ``/\``) are the *symbols*. + +An identifier can be used as a symbol but it must be surrounded by +single quotes to avoid the confusion with a parameter. Similarly, +every symbol of at least 3 characters and starting with a simple quote +must be quoted (then it starts by two single quotes). Here is an +example. + +.. coqtop:: in + + Notation "'IF' c1 'then' c2 'else' c3" := (IF_then_else c1 c2 c3). + +A notation binds a syntactic expression to a term. Unless the parser +and pretty-printer of Coq already know how to deal with the syntactic +expression (see :ref:`ReservingNotations`), explicit precedences and +associativity rules have to be given. + +.. note:: + + The right-hand side of a notation is interpreted at the time the notation is + given. In particular, disambiguation of constants, :ref:`implicit arguments + <ImplicitArguments>` and other notations are resolved at the + time of the declaration of the notation. + +Precedences and associativity +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Mixing different symbolic notations in the same text may cause serious +parsing ambiguity. To deal with the ambiguity of notations, Coq uses +precedence levels ranging from 0 to 100 (plus one extra level numbered +200) and associativity rules. + +Consider for example the new notation + +.. coqtop:: in + + Notation "A \/ B" := (or A B). + +Clearly, an expression such as :g:`forall A:Prop, True /\ A \/ A \/ False` +is ambiguous. To tell the Coq parser how to interpret the +expression, a priority between the symbols ``/\`` and ``\/`` has to be +given. Assume for instance that we want conjunction to bind more than +disjunction. This is expressed by assigning a precedence level to each +notation, knowing that a lower level binds more than a higher level. +Hence the level for disjunction must be higher than the level for +conjunction. + +Since connectives are not tight articulation points of a text, it +is reasonable to choose levels not so far from the highest level which +is 100, for example 85 for disjunction and 80 for conjunction [#and_or_levels]_. + +Similarly, an associativity is needed to decide whether :g:`True /\ False /\ False` +defaults to :g:`True /\ (False /\ False)` (right associativity) or to +:g:`(True /\ False) /\ False` (left associativity). We may even consider that the +expression is not well-formed and that parentheses are mandatory (this is a “no +associativity”) [#no_associativity]_. We do not know of a special convention of +the associativity of disjunction and conjunction, so let us apply for instance a +right associativity (which is the choice of Coq). + +Precedence levels and associativity rules of notations have to be +given between parentheses in a list of modifiers that the :cmd:`Notation` +command understands. Here is how the previous examples refine. + +.. coqtop:: in + + Notation "A /\ B" := (and A B) (at level 80, right associativity). + Notation "A \/ B" := (or A B) (at level 85, right associativity). + +By default, a notation is considered nonassociative, but the +precedence level is mandatory (except for special cases whose level is +canonical). The level is either a number or the phrase ``next level`` +whose meaning is obvious. +Some :ref:`associativities are predefined <init-notations>` in the +``Notations`` module. + +.. TODO I don't find it obvious -- CPC + +Complex notations +~~~~~~~~~~~~~~~~~ + +Notations can be made from arbitrarily complex symbols. One can for +instance define prefix notations. + +.. coqtop:: in + + Notation "~ x" := (not x) (at level 75, right associativity). + +One can also define notations for incomplete terms, with the hole +expected to be inferred during type checking. + +.. coqtop:: in + + Notation "x = y" := (@eq _ x y) (at level 70, no associativity). + +One can define *closed* notations whose both sides are symbols. In this case, +the default precedence level for the inner sub-expression is 200, and the default +level for the notation itself is 0. + +.. coqtop:: in + + Notation "( x , y )" := (@pair _ _ x y). + +One can also define notations for binders. + +.. coqtop:: in + + Notation "{ x : A | P }" := (sig A (fun x => P)). + +In the last case though, there is a conflict with the notation for +type casts. The notation for types casts, as shown by the command :cmd:`Print +Grammar constr` is at level 100. To avoid ``x : A`` being parsed as a type cast, +it is necessary to put ``x`` at a level below 100, typically 99. Hence, a correct +definition is the following: + +.. coqtop:: all + + Notation "{ x : A | P }" := (sig A (fun x => P)) (x at level 99). + +More generally, it is required that notations are explicitly factorized on the +left. See the next section for more about factorization. + +Simple factorization rules +~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Coq extensible parsing is performed by *Camlp5* which is essentially a LL1 +parser: it decides which notation to parse by looking at tokens from left to right. +Hence, some care has to be taken not to hide already existing rules by new +rules. Some simple left factorization work has to be done. Here is an example. + +.. coqtop:: all + + Notation "x < y" := (lt x y) (at level 70). + Fail Notation "x < y < z" := (x < y /\ y < z) (at level 70). + +In order to factorize the left part of the rules, the subexpression +referred to by ``y`` has to be at the same level in both rules. However the +default behavior puts ``y`` at the next level below 70 in the first rule +(``no associativity`` is the default), and at level 200 in the second +rule (``level 200`` is the default for inner expressions). To fix this, we +need to force the parsing level of ``y``, as follows. + +.. coqtop:: in + + Notation "x < y" := (lt x y) (at level 70). + Notation "x < y < z" := (x < y /\ y < z) (at level 70, y at next level). + +For the sake of factorization with Coq predefined rules, simple rules +have to be observed for notations starting with a symbol, e.g., rules +starting with “\ ``{``\ ” or “\ ``(``\ ” should be put at level 0. The list +of Coq predefined notations can be found in the chapter on :ref:`thecoqlibrary`. + +.. cmd:: Print Grammar constr. + + This command displays the current state of the Coq term parser. + +.. cmd:: Print Grammar pattern. + + This displays the state of the subparser of patterns (the parser used in the + grammar of the ``match with`` constructions). + + +Displaying symbolic notations +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +The command :cmd:`Notation` has an effect both on the Coq parser and on the +Coq printer. For example: + +.. coqtop:: all + + Check (and True True). + +However, printing, especially pretty-printing, also requires some +care. We may want specific indentations, line breaks, alignment if on +several lines, etc. For pretty-printing, |Coq| relies on |ocaml| +formatting library, which provides indentation and automatic line +breaks depending on page width by means of *formatting boxes*. + +The default printing of notations is rudimentary. For printing a +notation, a formatting box is opened in such a way that if the +notation and its arguments cannot fit on a single line, a line break +is inserted before the symbols of the notation and the arguments on +the next lines are aligned with the argument on the first line. + +A first, simple control that a user can have on the printing of a +notation is the insertion of spaces at some places of the notation. +This is performed by adding extra spaces between the symbols and +parameters: each extra space (other than the single space needed to +separate the components) is interpreted as a space to be inserted by +the printer. Here is an example showing how to add spaces around the +bar of the notation. + +.. coqtop:: in + + Notation "{{ x : A | P }}" := (sig (fun x : A => P)) (at level 0, x at level 99). + +.. coqtop:: all + + Check (sig (fun x : nat => x=x)). + +The second, more powerful control on printing is by using the format +modifier. Here is an example + +.. coqtop:: all + + Notation "'If' c1 'then' c2 'else' c3" := (IF_then_else c1 c2 c3) + (at level 200, right associativity, format + "'[v ' 'If' c1 '/' '[' 'then' c2 ']' '/' '[' 'else' c3 ']' ']'"). + +.. coqtop:: all + + Check + (IF_then_else (IF_then_else True False True) + (IF_then_else True False True) + (IF_then_else True False True)). + +A *format* is an extension of the string denoting the notation with +the possible following elements delimited by single quotes: + +- extra spaces are translated into simple spaces + +- tokens of the form ``'/ '`` are translated into breaking point, in + case a line break occurs, an indentation of the number of spaces after + the “ ``/``” is applied (2 spaces in the given example) + +- token of the form ``'//'`` force writing on a new line + +- well-bracketed pairs of tokens of the form ``'[ '`` and ``']'`` are + translated into printing boxes; in case a line break occurs, an extra + indentation of the number of spaces given after the “ ``[``” is applied + (4 spaces in the example) + +- well-bracketed pairs of tokens of the form ``'[hv '`` and ``']'`` are + translated into horizontal-or-else-vertical printing boxes; if the + content of the box does not fit on a single line, then every breaking + point forces a newline and an extra indentation of the number of + spaces given after the “ ``[``” is applied at the beginning of each + newline (3 spaces in the example) + +- well-bracketed pairs of tokens of the form ``'[v '`` and ``']'`` are + translated into vertical printing boxes; every breaking point forces a + newline, even if the line is large enough to display the whole content + of the box, and an extra indentation of the number of spaces given + after the “``[``” is applied at the beginning of each newline + +Notations disappear when a section is closed. No typing of the denoted +expression is performed at definition time. Type checking is done only +at the time of use of the notation. + +.. note:: Sometimes, a notation is expected only for the parser. To do + so, the option ``only parsing`` is allowed in the list of modifiers + of :cmd:`Notation`. Conversely, the ``only printing`` modifier can be + used to declare that a notation should only be used for printing and + should not declare a parsing rule. In particular, such notations do + not modify the parser. + +The Infix command +~~~~~~~~~~~~~~~~~~ + +The :cmd:`Infix` command is a shortening for declaring notations of infix +symbols. + +.. cmd:: Infix "@symbol" := @term ({+, @modifier}). + + This command is equivalent to + + :n:`Notation "x @symbol y" := (@term x y) ({+, @modifier}).` + + where ``x`` and ``y`` are fresh names. Here is an example. + + .. coqtop:: in + + Infix "/\" := and (at level 80, right associativity). + +.. _ReservingNotations: + +Reserving notations +~~~~~~~~~~~~~~~~~~~ + +A given notation may be used in different contexts. Coq expects all +uses of the notation to be defined at the same precedence and with the +same associativity. To avoid giving the precedence and associativity +every time, it is possible to declare a parsing rule in advance +without giving its interpretation. Here is an example from the initial +state of Coq. + +.. coqtop:: in + + Reserved Notation "x = y" (at level 70, no associativity). + +Reserving a notation is also useful for simultaneously defining an +inductive type or a recursive constant and a notation for it. + +.. note:: The notations mentioned in the module :ref:`init-notations` are reserved. Hence + their precedence and associativity cannot be changed. + +Simultaneous definition of terms and notations +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Thanks to reserved notations, the inductive, co-inductive, record, recursive and +corecursive definitions can benefit from customized notations. To do this, insert +a ``where`` notation clause after the definition of the (co)inductive type or +(co)recursive term (or after the definition of each of them in case of mutual +definitions). The exact syntax is given by :token:`decl_notation` for inductive, +co-inductive, recursive and corecursive definitions and in :ref:`record-types` +for records. Here are examples: + +.. coqtop:: in + + Reserved Notation "A & B" (at level 80). + +.. coqtop:: in + + Inductive and' (A B : Prop) : Prop := conj' : A -> B -> A & B + where "A & B" := (and' A B). + +.. coqtop:: in + + Fixpoint plus (n m : nat) {struct n} : nat := + match n with + | O => m + | S p => S (p+m) + end + where "n + m" := (plus n m). + +Displaying information about notations +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. flag:: Printing Notations + + Controls whether to use notations for printing terms wherever possible. + Default is on. + +.. seealso:: + + :flag:`Printing All` + To disable other elements in addition to notations. + +.. _locating-notations: + +Locating notations +~~~~~~~~~~~~~~~~~~ + +To know to which notations a given symbol belongs to, use the :cmd:`Locate` +command. You can call it on any (composite) symbol surrounded by double quotes. +To locate a particular notation, use a string where the variables of the +notation are replaced by “``_``” and where possible single quotes inserted around +identifiers or tokens starting with a single quote are dropped. + +.. coqtop:: all + + Locate "exists". + Locate "exists _ .. _ , _". + +Notations and binders +~~~~~~~~~~~~~~~~~~~~~ + +Notations can include binders. This section lists +different ways to deal with binders. For further examples, see also +:ref:`RecursiveNotationsWithBinders`. + +Binders bound in the notation and parsed as identifiers ++++++++++++++++++++++++++++++++++++++++++++++++++++++++ + +Here is the basic example of a notation using a binder: + +.. coqtop:: in + + Notation "'sigma' x : A , B" := (sigT (fun x : A => B)) + (at level 200, x ident, A at level 200, right associativity). + +The binding variables in the right-hand side that occur as a parameter +of the notation (here :g:`x`) dynamically bind all the occurrences +in their respective binding scope after instantiation of the +parameters of the notation. This means that the term bound to :g:`B` can +refer to the variable name bound to :g:`x` as shown in the following +application of the notation: + +.. coqtop:: all + + Check sigma z : nat, z = 0. + +Notice the modifier ``x ident`` in the declaration of the +notation. It tells to parse :g:`x` as a single identifier. + +Binders bound in the notation and parsed as patterns +++++++++++++++++++++++++++++++++++++++++++++++++++++ + +In the same way as patterns can be used as binders, as in +:g:`fun '(x,y) => x+y` or :g:`fun '(existT _ x _) => x`, notations can be +defined so that any :n:`@pattern` can be used in place of the +binder. Here is an example: + +.. coqtop:: in reset + + Notation "'subset' ' p , P " := (sig (fun p => P)) + (at level 200, p pattern, format "'subset' ' p , P"). + +.. coqtop:: all + + Check subset '(x,y), x+y=0. + +The modifier ``p pattern`` in the declaration of the notation tells to parse +:g:`p` as a pattern. Note that a single variable is both an identifier and a +pattern, so, e.g., the following also works: + +.. coqtop:: all + + Check subset 'x, x=0. + +If one wants to prevent such a notation to be used for printing when the +pattern is reduced to a single identifier, one has to use instead +the modifier ``p strict pattern``. For parsing, however, a +``strict pattern`` will continue to include the case of a +variable. Here is an example showing the difference: + +.. coqtop:: in + + Notation "'subset_bis' ' p , P" := (sig (fun p => P)) + (at level 200, p strict pattern). + Notation "'subset_bis' p , P " := (sig (fun p => P)) + (at level 200, p ident). + +.. coqtop:: all + + Check subset_bis 'x, x=0. + +The default level for a ``pattern`` is 0. One can use a different level by +using ``pattern at level`` :math:`n` where the scale is the same as the one for +terms (see :ref:`init-notations`). + +Binders bound in the notation and parsed as terms ++++++++++++++++++++++++++++++++++++++++++++++++++ + +Sometimes, for the sake of factorization of rules, a binder has to be +parsed as a term. This is typically the case for a notation such as +the following: + +.. coqdoc:: + + Notation "{ x : A | P }" := (sig (fun x : A => P)) + (at level 0, x at level 99 as ident). + +This is so because the grammar also contains rules starting with :g:`{}` and +followed by a term, such as the rule for the notation :g:`{ A } + { B }` for the +constant :g:`sumbool` (see :ref:`specification`). + +Then, in the rule, ``x ident`` is replaced by ``x at level 99 as ident`` meaning +that ``x`` is parsed as a term at level 99 (as done in the notation for +:g:`sumbool`), but that this term has actually to be an identifier. + +The notation :g:`{ x | P }` is already defined in the standard +library with the ``as ident`` modifier. We cannot redefine it but +one can define an alternative notation, say :g:`{ p such that P }`, +using instead ``as pattern``. + +.. coqtop:: in + + Notation "{ p 'such' 'that' P }" := (sig (fun p => P)) + (at level 0, p at level 99 as pattern). + +Then, the following works: + +.. coqtop:: all + + Check {(x,y) such that x+y=0}. + +To enforce that the pattern should not be used for printing when it +is just an identifier, one could have said +``p at level 99 as strict pattern``. + +Note also that in the absence of a ``as ident``, ``as strict pattern`` or +``as pattern`` modifiers, the default is to consider sub-expressions occurring +in binding position and parsed as terms to be ``as ident``. + +.. _NotationsWithBinders: + +Binders not bound in the notation ++++++++++++++++++++++++++++++++++ + +We can also have binders in the right-hand side of a notation which +are not themselves bound in the notation. In this case, the binders +are considered up to renaming of the internal binder. E.g., for the +notation + +.. coqtop:: in + + Notation "'exists_different' n" := (exists p:nat, p<>n) (at level 200). + +the next command fails because p does not bind in the instance of n. + +.. coqtop:: all + + Fail Check (exists_different p). + +.. coqtop:: in + + Notation "[> a , .. , b <]" := + (cons a .. (cons b nil) .., cons b .. (cons a nil) ..). + +.. _RecursiveNotations: + +Notations with recursive patterns +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +A mechanism is provided for declaring elementary notations with +recursive patterns. The basic example is: + +.. coqtop:: all + + Notation "[ x ; .. ; y ]" := (cons x .. (cons y nil) ..). + +On the right-hand side, an extra construction of the form ``.. t ..`` can +be used. Notice that ``..`` is part of the Coq syntax and it must not be +confused with the three-dots notation “``…``” used in this manual to denote +a sequence of arbitrary size. + +On the left-hand side, the part “``x s .. s y``” of the notation parses +any number of times (but at least once) a sequence of expressions +separated by the sequence of tokens ``s`` (in the example, ``s`` is just “``;``”). + +The right-hand side must contain a subterm of the form either +``φ(x, .. φ(y,t) ..)`` or ``φ(y, .. φ(x,t) ..)`` where :math:`φ([~]_E , [~]_I)`, +called the *iterator* of the recursive notation is an arbitrary expression with +distinguished placeholders and where :math:`t` is called the *terminating +expression* of the recursive notation. In the example, we choose the names +:math:`x` and :math:`y` but in practice they can of course be chosen +arbitrarily. Note that the placeholder :math:`[~]_I` has to occur only once but +:math:`[~]_E` can occur several times. + +Parsing the notation produces a list of expressions which are used to +fill the first placeholder of the iterating pattern which itself is +repeatedly nested as many times as the length of the list, the second +placeholder being the nesting point. In the innermost occurrence of the +nested iterating pattern, the second placeholder is finally filled with the +terminating expression. + +In the example above, the iterator :math:`φ([~]_E , [~]_I)` is :math:`cons [~]_E [~]_I` +and the terminating expression is ``nil``. Here are other examples: + +.. coqtop:: in + + Notation "( x , y , .. , z )" := (pair .. (pair x y) .. z) (at level 0). + + Notation "[| t * ( x , y , .. , z ) ; ( a , b , .. , c ) * u |]" := + (pair (pair .. (pair (pair t x) (pair t y)) .. (pair t z)) + (pair .. (pair (pair a u) (pair b u)) .. (pair c u))) + (t at level 39). + +Notations with recursive patterns can be reserved like standard +notations, they can also be declared within +:ref:`interpretation scopes <Scopes>`. + +.. _RecursiveNotationsWithBinders: + +Notations with recursive patterns involving binders +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Recursive notations can also be used with binders. The basic example +is: + +.. coqtop:: in + + Notation "'exists' x .. y , p" := + (ex (fun x => .. (ex (fun y => p)) ..)) + (at level 200, x binder, y binder, right associativity). + +The principle is the same as in :ref:`RecursiveNotations` +except that in the iterator +:math:`φ([~]_E , [~]_I)`, the placeholder :math:`[~]_E` can also occur in +position of the binding variable of a ``fun`` or a ``forall``. + +To specify that the part “``x .. y``” of the notation parses a sequence of +binders, ``x`` and ``y`` must be marked as ``binder`` in the list of modifiers +of the notation. The binders of the parsed sequence are used to fill the +occurrences of the first placeholder of the iterating pattern which is +repeatedly nested as many times as the number of binders generated. If ever the +generalization operator ``'`` (see :ref:`implicit-generalization`) is +used in the binding list, the added binders are taken into account too. + +There are two flavors of binder parsing. If ``x`` and ``y`` are marked as binder, +then a sequence such as :g:`a b c : T` will be accepted and interpreted as +the sequence of binders :g:`(a:T) (b:T) (c:T)`. For instance, in the +notation above, the syntax :g:`exists a b : nat, a = b` is valid. + +The variables ``x`` and ``y`` can also be marked as closed binder in which +case only well-bracketed binders of the form :g:`(a b c:T)` or :g:`{a b c:T}` +etc. are accepted. + +With closed binders, the recursive sequence in the left-hand side can +be of the more general form ``x s .. s y`` where ``s`` is an arbitrary sequence of +tokens. With open binders though, ``s`` has to be empty. Here is an +example of recursive notation with closed binders: + +.. coqtop:: in + + Notation "'mylet' f x .. y := t 'in' u":= + (let f := fun x => .. (fun y => t) .. in u) + (at level 200, x closed binder, y closed binder, right associativity). + +A recursive pattern for binders can be used in position of a recursive +pattern for terms. Here is an example: + +.. coqtop:: in + + Notation "'FUNAPP' x .. y , f" := + (fun x => .. (fun y => (.. (f x) ..) y ) ..) + (at level 200, x binder, y binder, right associativity). + +If an occurrence of the :math:`[~]_E` is not in position of a binding +variable but of a term, it is the name used in the binding which is +used. Here is an example: + +.. coqtop:: in + + Notation "'exists_non_null' x .. y , P" := + (ex (fun x => x <> 0 /\ .. (ex (fun y => y <> 0 /\ P)) ..)) + (at level 200, x binder). + +Predefined entries +~~~~~~~~~~~~~~~~~~ + +By default, sub-expressions are parsed as terms and the corresponding +grammar entry is called :n:`@constr`. However, one may sometimes want +to restrict the syntax of terms in a notation. For instance, the +following notation will accept to parse only global reference in +position of :g:`x`: + +.. coqtop:: in + + Notation "'apply' f a1 .. an" := (.. (f a1) .. an) + (at level 10, f global, a1, an at level 9). + +In addition to ``global``, one can restrict the syntax of a +sub-expression by using the entry names ``ident`` or ``pattern`` +already seen in :ref:`NotationsWithBinders`, even when the +corresponding expression is not used as a binder in the right-hand +side. E.g.: + +.. coqtop:: in + + Notation "'apply_id' f a1 .. an" := (.. (f a1) .. an) + (at level 10, f ident, a1, an at level 9). + +.. _custom-entries: + +Custom entries +~~~~~~~~~~~~~~ + +.. cmd:: Declare Custom Entry @ident + + This command allows to define new grammar entries, called *custom + entries*, that can later be referred to using the entry name + :n:`custom @ident`. + +.. example:: + + For instance, we may want to define an ad hoc + parser for arithmetical operations and proceed as follows: + + .. coqtop:: all + + Inductive Expr := + | One : Expr + | Mul : Expr -> Expr -> Expr + | Add : Expr -> Expr -> Expr. + + Declare Custom Entry expr. + Notation "[ e ]" := e (e custom expr at level 2). + Notation "1" := One (in custom expr at level 0). + Notation "x y" := (Mul x y) (in custom expr at level 1, left associativity). + Notation "x + y" := (Add x y) (in custom expr at level 2, left associativity). + Notation "( x )" := x (in custom expr, x at level 2). + Notation "{ x }" := x (in custom expr, x constr). + Notation "x" := x (in custom expr at level 0, x ident). + + Axiom f : nat -> Expr. + Check fun x y z => [1 + y z + {f x}]. + Unset Printing Notations. + Check fun x y z => [1 + y z + {f x}]. + Set Printing Notations. + Check fun e => match e with + | [1 + 1] => [1] + | [x y + z] => [x + y z] + | y => [y + e] + end. + +Custom entries have levels, like the main grammar of terms and grammar +of patterns have. The lower level is 0 and this is the level used by +default to put rules delimited with tokens on both ends. The level is +left to be inferred by Coq when using :n:`in custom @ident`. The +level is otherwise given explicitly by using the syntax +:n:`in custom @ident at level @num`, where :n:`@num` refers to the level. + +Levels are cumulative: a notation at level ``n`` of which the left end +is a term shall use rules at level less than ``n`` to parse this +sub-term. More precisely, it shall use rules at level strictly less +than ``n`` if the rule is declared with ``right associativity`` and +rules at level less or equal than ``n`` if the rule is declared with +``left associativity``. Similarly, a notation at level ``n`` of which +the right end is a term shall use by default rules at level strictly +less than ``n`` to parse this sub-term if the rule is declared left +associative and rules at level less or equal than ``n`` if the rule is +declared right associative. This is what happens for instance in the +rule + +.. coqtop:: in + + Notation "x + y" := (Add x y) (in custom expr at level 2, left associativity). + +where ``x`` is any expression parsed in entry +``expr`` at level less or equal than ``2`` (including, recursively, +the given rule) and ``y`` is any expression parsed in entry ``expr`` +at level strictly less than ``2``. + +Rules associated to an entry can refer different sub-entries. The +grammar entry name ``constr`` can be used to refer to the main grammar +of term as in the rule + +.. coqtop:: in + + Notation "{ x }" := x (in custom expr at level 0, x constr). + +which indicates that the subterm ``x`` should be +parsed using the main grammar. If not indicated, the level is computed +as for notations in ``constr``, e.g. using 200 as default level for +inner sub-expressions. The level can otherwise be indicated explicitly +by using ``constr at level n`` for some ``n``, or ``constr at next +level``. + +Conversely, custom entries can be used to parse sub-expressions of the +main grammar, or from another custom entry as is the case in + +.. coqtop:: in + + Notation "[ e ]" := e (e custom expr at level 2). + +to indicate that ``e`` has to be parsed at level ``2`` of the grammar +associated to the custom entry ``expr``. The level can be omitted, as in + +.. coqdoc:: + + Notation "[ e ]" := e (e custom expr). + +in which case Coq tries to infer it. + +In the absence of an explicit entry for parsing or printing a +sub-expression of a notation in a custom entry, the default is to +consider that this sub-expression is parsed or printed in the same +custom entry where the notation is defined. In particular, if ``x at +level n`` is used for a sub-expression of a notation defined in custom +entry ``foo``, it shall be understood the same as ``x custom foo at +level n``. + +In general, rules are required to be *productive* on the right-hand +side, i.e. that they are bound to an expression which is not +reduced to a single variable. If the rule is not productive on the +right-hand side, as it is the case above for + +.. coqtop:: in + + Notation "( x )" := x (in custom expr at level 0, x at level 2). + +and + +.. coqtop:: in + + Notation "{ x }" := x (in custom expr at level 0, x constr). + +it is used as a *grammar coercion* which means that it is used to parse or +print an expression which is not available in the current grammar at the +current level of parsing or printing for this grammar but which is available +in another grammar or in another level of the current grammar. For instance, + +.. coqtop:: in + + Notation "( x )" := x (in custom expr at level 0, x at level 2). + +tells that parentheses can be inserted to parse or print an expression +declared at level ``2`` of ``expr`` whenever this expression is +expected to be used as a subterm at level 0 or 1. This allows for +instance to parse and print :g:`Add x y` as a subterm of :g:`Mul (Add +x y) z` using the syntax ``(x + y) z``. Similarly, + +.. coqtop:: in + + Notation "{ x }" := x (in custom expr at level 0, x constr). + +gives a way to let any arbitrary expression which is not handled by the +custom entry ``expr`` be parsed or printed by the main grammar of term +up to the insertion of a pair of curly brackets. + +.. cmd:: Print Grammar @ident. + + This displays the state of the grammar for terms and grammar for + patterns associated to the custom entry :token:`ident`. + +Summary +~~~~~~~ + +.. _NotationSyntax: + +Syntax of notations ++++++++++++++++++++ + +The different syntactic forms taken by the commands declaring +notations are given below. The optional :production:`scope` is described in +:ref:`Scopes`. + +.. productionlist:: coq + notation : [Local] Notation `string` := `term` [`modifiers`] [: `scope`]. + : [Local] Infix `string` := `qualid` [`modifiers`] [: `scope`]. + : [Local] Reserved Notation `string` [`modifiers`] . + : Inductive `ind_body` [`decl_notation`] with … with `ind_body` [`decl_notation`]. + : CoInductive `ind_body` [`decl_notation`] with … with `ind_body` [`decl_notation`]. + : Fixpoint `fix_body` [`decl_notation`] with … with `fix_body` [`decl_notation`]. + : CoFixpoint `cofix_body` [`decl_notation`] with … with `cofix_body` [`decl_notation`]. + : [Local] Declare Custom Entry `ident`. + decl_notation : [where `string` := `term` [: `scope`] and … and `string` := `term` [: `scope`]]. + modifiers : at level `num` + : in custom `ident` + : in custom `ident` at level `num` + : `ident` , … , `ident` at level `num` [`binderinterp`] + : `ident` , … , `ident` at next level [`binderinterp`] + : `ident` `explicit_subentry` + : left associativity + : right associativity + : no associativity + : only parsing + : only printing + : format `string` + explicit_subentry : ident + : global + : bigint + : [strict] pattern [at level `num`] + : binder + : closed binder + : constr [`binderinterp`] + : constr at level `num` [`binderinterp`] + : constr at next level [`binderinterp`] + : custom [`binderinterp`] + : custom at level `num` [`binderinterp`] + : custom at next level [`binderinterp`] + binderinterp : as ident + : as pattern + : as strict pattern + +.. note:: No typing of the denoted expression is performed at definition + time. Type checking is done only at the time of use of the notation. + +.. note:: Some examples of Notation may be found in the files composing + the initial state of Coq (see directory :file:`$COQLIB/theories/Init`). + +.. note:: The notation ``"{ x }"`` has a special status in the main grammars of + terms and patterns so that + complex notations of the form ``"x + { y }"`` or ``"x * { y }"`` can be + nested with correct precedences. Especially, every notation involving + a pattern of the form ``"{ x }"`` is parsed as a notation where the + pattern ``"{ x }"`` has been simply replaced by ``"x"`` and the curly + brackets are parsed separately. E.g. ``"y + { z }"`` is not parsed as a + term of the given form but as a term of the form ``"y + z"`` where ``z`` + has been parsed using the rule parsing ``"{ x }"``. Especially, level + and precedences for a rule including patterns of the form ``"{ x }"`` + are relative not to the textual notation but to the notation where the + curly brackets have been removed (e.g. the level and the associativity + given to some notation, say ``"{ y } & { z }"`` in fact applies to the + underlying ``"{ x }"``\-free rule which is ``"y & z"``). + +Persistence of notations +++++++++++++++++++++++++ + +Notations disappear when a section is closed. + +.. cmd:: Local Notation @notation + + Notations survive modules unless the command ``Local Notation`` is used instead + of :cmd:`Notation`. + +.. cmd:: Local Declare Custom Entry @ident + + Custom entries survive modules unless the command ``Local Declare + Custom Entry`` is used instead of :cmd:`Declare Custom Entry`. + +.. _Scopes: + +Interpretation scopes +---------------------- + +An *interpretation scope* is a set of notations for terms with their +interpretations. Interpretation scopes provide a weak, purely +syntactical form of notation overloading: the same notation, for +instance the infix symbol ``+``, can be used to denote distinct +definitions of the additive operator. Depending on which interpretation +scopes are currently open, the interpretation is different. +Interpretation scopes can include an interpretation for numerals and +strings, either at the OCaml level or using :cmd:`Numeral Notation` +or :cmd:`String Notation`. + +.. cmd:: Declare Scope @scope + + This adds a new scope named :n:`@scope`. Note that the initial + state of Coq declares by default the following interpretation scopes: + ``core_scope``, ``type_scope``, ``function_scope``, ``nat_scope``, + ``bool_scope``, ``list_scope``, ``int_scope``, ``uint_scope``. + +The syntax to associate a notation to a scope is given +:ref:`above <NotationSyntax>`. Here is a typical example which declares the +notation for conjunction in the scope ``type_scope``. + +.. coqtop:: in + + Notation "A /\ B" := (and A B) : type_scope. + +.. note:: A notation not defined in a scope is called a *lonely* + notation. No example of lonely notations can be found in the + initial state of Coq though. + + +Global interpretation rules for notations +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +At any time, the interpretation of a notation for a term is done within +a *stack* of interpretation scopes and lonely notations. In case a +notation has several interpretations, the actual interpretation is the +one defined by (or in) the more recently declared (or opened) lonely +notation (or interpretation scope) which defines this notation. +Typically if a given notation is defined in some scope ``scope`` but has +also an interpretation not assigned to a scope, then, if ``scope`` is open +before the lonely interpretation is declared, then the lonely +interpretation is used (and this is the case even if the +interpretation of the notation in scope is given after the lonely +interpretation: otherwise said, only the order of lonely +interpretations and opening of scopes matters, and not the declaration +of interpretations within a scope). + +.. cmd:: Open Scope @scope + + The command to add a scope to the interpretation scope stack is + :n:`Open Scope @scope`. + +.. cmd:: Close Scope @scope + + It is also possible to remove a scope from the interpretation scope + stack by using the command :n:`Close Scope @scope`. + + Notice that this command does not only cancel the last :n:`Open Scope @scope` + but all its invocations. + +.. note:: ``Open Scope`` and ``Close Scope`` do not survive the end of sections + where they occur. When defined outside of a section, they are exported + to the modules that import the module where they occur. + +.. cmd:: Local Open Scope @scope. + Local Close Scope @scope. + + These variants are not exported to the modules that import the module where + they occur, even if outside a section. + +.. cmd:: Global Open Scope @scope. + Global Close Scope @scope. + + These variants survive sections. They behave as if Global were absent when + not inside a section. + +.. _LocalInterpretationRulesForNotations: + +Local interpretation rules for notations +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +In addition to the global rules of interpretation of notations, some +ways to change the interpretation of subterms are available. + +Local opening of an interpretation scope ++++++++++++++++++++++++++++++++++++++++++ + +It is possible to locally extend the interpretation scope stack using the syntax +:g:`(term)%key` (or simply :g:`term%key` for atomic terms), where key is a +special identifier called *delimiting key* and bound to a given scope. + +In such a situation, the term term, and all its subterms, are +interpreted in the scope stack extended with the scope bound tokey. + +.. cmd:: Delimit Scope @scope with @ident + + To bind a delimiting key to a scope, use the command + :n:`Delimit Scope @scope with @ident` + +.. cmd:: Undelimit Scope @scope + + To remove a delimiting key of a scope, use the command + :n:`Undelimit Scope @scope` + +.. _ArgumentScopes: + +Binding arguments of a constant to an interpretation scope ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ + +.. cmd:: Arguments @qualid {+ @name%@scope} + :name: Arguments (scopes) + + It is possible to set in advance that some arguments of a given constant have + to be interpreted in a given scope. The command is + :n:`Arguments @qualid {+ @name%@scope}` where the list is a prefix of the + arguments of ``qualid`` eventually annotated with their ``scope``. Grouping + round parentheses can be used to decorate multiple arguments with the same + scope. ``scope`` can be either a scope name or its delimiting key. For + example the following command puts the first two arguments of :g:`plus_fct` + in the scope delimited by the key ``F`` (``Rfun_scope``) and the last + argument in the scope delimited by the key ``R`` (``R_scope``). + + .. coqdoc:: + + Arguments plus_fct (f1 f2)%F x%R. + + The ``Arguments`` command accepts scopes decoration to all grouping + parentheses. In the following example arguments A and B are marked as + maximally inserted implicit arguments and are put into the type_scope scope. + + .. coqdoc:: + + Arguments respectful {A B}%type (R R')%signature _ _. + + When interpreting a term, if some of the arguments of qualid are built + from a notation, then this notation is interpreted in the scope stack + extended by the scope bound (if any) to this argument. The effect of + the scope is limited to the argument itself. It does not propagate to + subterms but the subterms that, after interpretation of the notation, + turn to be themselves arguments of a reference are interpreted + accordingly to the argument scopes bound to this reference. + + .. cmdv:: Arguments @qualid : clear scopes + + This command can be used to clear argument scopes of :token:`qualid`. + + .. cmdv:: Arguments @qualid {+ @name%scope} : extra scopes + + Defines extra argument scopes, to be used in case of coercion to ``Funclass`` + (see the :ref:`implicitcoercions` chapter) or with a computed type. + + .. cmdv:: Global Arguments @qualid {+ @name%@scope} + + This behaves like :n:`Arguments qualid {+ @name%@scope}` but survives when a + section is closed instead of stopping working at section closing. Without the + ``Global`` modifier, the effect of the command stops when the section it belongs + to ends. + + .. cmdv:: Local Arguments @qualid {+ @name%@scope} + + This behaves like :n:`Arguments @qualid {+ @name%@scope}` but does not + survive modules and files. Without the ``Local`` modifier, the effect of the + command is visible from within other modules or files. + +.. seealso:: + + The command :cmd:`About` can be used to show the scopes bound to the + arguments of a function. + +.. note:: + + In notations, the subterms matching the identifiers of the + notations are interpreted in the scope in which the identifiers + occurred at the time of the declaration of the notation. Here is an + example: + + .. coqtop:: all + + Parameter g : bool -> bool. + Declare Scope mybool_scope. + + Notation "@@" := true (only parsing) : bool_scope. + Notation "@@" := false (only parsing): mybool_scope. + + Bind Scope bool_scope with bool. + Notation "# x #" := (g x) (at level 40). + Check # @@ #. + Arguments g _%mybool_scope. + Check # @@ #. + Delimit Scope mybool_scope with mybool. + Check # @@%mybool #. + +Binding types of arguments to an interpretation scope ++++++++++++++++++++++++++++++++++++++++++++++++++++++ + +.. cmd:: Bind Scope @scope with @qualid + + When an interpretation scope is naturally associated to a type (e.g. the + scope of operations on the natural numbers), it may be convenient to bind it + to this type. When a scope ``scope`` is bound to a type ``type``, any new function + defined later on gets its arguments of type ``type`` interpreted by default in + scope scope (this default behavior can however be overwritten by explicitly + using the command :cmd:`Arguments`). + + Whether the argument of a function has some type ``type`` is determined + statically. For instance, if ``f`` is a polymorphic function of type + :g:`forall X:Type, X -> X` and type :g:`t` is bound to a scope ``scope``, + then :g:`a` of type :g:`t` in :g:`f t a` is not recognized as an argument to + be interpreted in scope ``scope``. + + More generally, any coercion :n:`@class` (see the :ref:`implicitcoercions` chapter) + can be bound to an interpretation scope. The command to do it is + :n:`Bind Scope @scope with @class` + + .. coqtop:: in reset + + Parameter U : Set. + Declare Scope U_scope. + Bind Scope U_scope with U. + Parameter Uplus : U -> U -> U. + Parameter P : forall T:Set, T -> U -> Prop. + Parameter f : forall T:Set, T -> U. + Infix "+" := Uplus : U_scope. + Unset Printing Notations. + Open Scope nat_scope. + + .. coqtop:: all + + Check (fun x y1 y2 z t => P _ (x + t) ((f _ (y1 + y2) + z))). + + .. note:: The scopes ``type_scope`` and ``function_scope`` also have a local + effect on interpretation. See the next section. + +The ``type_scope`` interpretation scope +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. index:: type_scope + +The scope ``type_scope`` has a special status. It is a primitive interpretation +scope which is temporarily activated each time a subterm of an expression is +expected to be a type. It is delimited by the key ``type``, and bound to the +coercion class ``Sortclass``. It is also used in certain situations where an +expression is statically known to be a type, including the conclusion and the +type of hypotheses within an Ltac goal match (see +:ref:`ltac-match-goal`), the statement of a theorem, the type of a definition, +the type of a binder, the domain and codomain of implication, the codomain of +products, and more generally any type argument of a declared or defined +constant. + +The ``function_scope`` interpretation scope +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. index:: function_scope + +The scope ``function_scope`` also has a special status. +It is temporarily activated each time the argument of a global reference is +recognized to be a ``Funclass`` istance, i.e., of type :g:`forall x:A, B` or +:g:`A -> B`. + + +Interpretation scopes used in the standard library of Coq +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +We give an overview of the scopes used in the standard library of Coq. +For a complete list of notations in each scope, use the commands :cmd:`Print +Scopes` or :cmd:`Print Scope`. + +``type_scope`` + This scope includes infix * for product types and infix + for sum types. It + is delimited by the key ``type``, and bound to the coercion class + ``Sortclass``, as described above. + +``function_scope`` + This scope is delimited by the key ``function``, and bound to the coercion class + ``Funclass``, as described above. + +``nat_scope`` + This scope includes the standard arithmetical operators and relations on type + nat. Positive integer numerals in this scope are mapped to their canonical + representent built from :g:`O` and :g:`S`. The scope is delimited by the key + ``nat``, and bound to the type :g:`nat` (see above). + +``N_scope`` + This scope includes the standard arithmetical operators and relations on + type :g:`N` (binary natural numbers). It is delimited by the key ``N`` and comes + with an interpretation for numerals as closed terms of type :g:`N`. + +``Z_scope`` + This scope includes the standard arithmetical operators and relations on + type :g:`Z` (binary integer numbers). It is delimited by the key ``Z`` and comes + with an interpretation for numerals as closed terms of type :g:`Z`. + +``positive_scope`` + This scope includes the standard arithmetical operators and relations on + type :g:`positive` (binary strictly positive numbers). It is delimited by + key ``positive`` and comes with an interpretation for numerals as closed + terms of type :g:`positive`. + +``Q_scope`` + This scope includes the standard arithmetical operators and relations on + type :g:`Q` (rational numbers defined as fractions of an integer and a + strictly positive integer modulo the equality of the numerator- + denominator cross-product) and comes with an interpretation for numerals + as closed terms of type :g:`Q`. + +``Qc_scope`` + This scope includes the standard arithmetical operators and relations on the + type :g:`Qc` of rational numbers defined as the type of irreducible + fractions of an integer and a strictly positive integer. + +``R_scope`` + This scope includes the standard arithmetical operators and relations on + type :g:`R` (axiomatic real numbers). It is delimited by the key ``R`` and comes + with an interpretation for numerals using the :g:`IZR` morphism from binary + integer numbers to :g:`R` and :g:`Z.pow_pos` for potential exponent parts. + +``bool_scope`` + This scope includes notations for the boolean operators. It is delimited by the + key ``bool``, and bound to the type :g:`bool` (see above). + +``list_scope`` + This scope includes notations for the list operators. It is delimited by the key + ``list``, and bound to the type :g:`list` (see above). + +``core_scope`` + This scope includes the notation for pairs. It is delimited by the key ``core``. + +``string_scope`` + This scope includes notation for strings as elements of the type string. + Special characters and escaping follow Coq conventions on strings (see + :ref:`lexical-conventions`). Especially, there is no convention to visualize non + printable characters of a string. The file :file:`String.v` shows an example + that contains quotes, a newline and a beep (i.e. the ASCII character + of code 7). + +``char_scope`` + This scope includes interpretation for all strings of the form ``"c"`` + where :g:`c` is an ASCII character, or of the form ``"nnn"`` where nnn is + a three-digits number (possibly with leading 0's), or of the form + ``""""``. Their respective denotations are the ASCII code of :g:`c`, the + decimal ASCII code ``nnn``, or the ascii code of the character ``"`` (i.e. + the ASCII code 34), all of them being represented in the type :g:`ascii`. + + +Displaying information about scopes +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. cmd:: Print Visibility + + This displays the current stack of notations in scopes and lonely + notations that is used to interpret a notation. The top of the stack + is displayed last. Notations in scopes whose interpretation is hidden + by the same notation in a more recently opened scope are not displayed. + Hence each notation is displayed only once. + + .. cmdv:: Print Visibility @scope + + This displays the current stack of notations in scopes and lonely + notations assuming that :token:`scope` is pushed on top of the stack. This is + useful to know how a subterm locally occurring in the scope :token:`scope` is + interpreted. + +.. cmd:: Print Scopes + + This displays all the notations, delimiting keys and corresponding + classes of all the existing interpretation scopes. It also displays the + lonely notations. + + .. cmdv:: Print Scope @scope + :name: Print Scope + + This displays all the notations defined in the interpretation scope :token:`scope`. + It also displays the delimiting key if any and the class to which the + scope is bound, if any. + +Impact of scopes on printing +~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +When several notations are available for printing the same expression, +Coq will use the following rules for printing priorities: + +- If two notations are available in different scopes which are open, + the notation in the more recently opened scope takes precedence. + +- If two notations are available in the same scope, the more recently + defined (or imported) notation takes precedence. + +- Abbreviations and lonely notations, both of which have no scope, + take precedence over a notation in an open scope if and only if the + abbreviation or lonely notation was defined (or imported) more + recently than when the corresponding scope was open. They take + precedence over any notation not in an open scope, whether this scope + has a delimiter or not. + +- A scope is *active* for printing a term either because it was opened + with :cmd:`Open Scope`, or the term is the immediate argument of a + constant which temporarily opens a scope for this argument (see + :ref:`Arguments <ArgumentScopes>`) in which case this temporary + scope is the most recent open one. + +- In case no abbreviation, nor lonely notation, nor notation in an + explicitly open scope, nor notation in a temporarily open scope of + arguments, has been found, notations in those closed scopes which + have a delimiter are considered, giving priority to the most + recently defined (or imported) ones. The corresponding delimiter is + inserted, making the corresponding scope the most recent explicitly + open scope for all subterms of the current term. As an exception to + the insertion of the corresponding delimiter, when an expression is + statically known to be in a position expecting a type and the + notation is from scope ``type_scope``, and the latter is closed, the + delimiter is not inserted. This is because expressions statically + known to be in a position expecting a type are by default + interpreted with `type_scope` temporarily activated. Expressions + statically known to be in a position expecting a type typically + include being on the right-hand side of `:`, `<:`, `<<:` and after + the comma in a `forall` expression. + +- As a refinement of the previous rule, in the case of applied global + references, notations in a non-opened scope with delimiter + specifically defined for this applied global reference take priority + over notations in a non-opened scope with delimiter for generic + applications. For instance, in the presence of ``Notation "f ( x + )" := (f x) (at level 10, format "f ( x )") : app_scope`` and + ``Notation "x '.+1'" := (S x) (at level 10, format "x '.+1'") : + mynat_scope.`` and both of ``app_scope`` and ``mynat_scope`` being + bound to a delimiter *and* both not opened, the latter, more + specific notation will always take precedence over the first, more + generic one. + +- A scope can be closed by using :cmd:`Close Scope` and its delimiter + removed by using :cmd:`Undelimit Scope`. To remove automatic + temporary opening of scopes for arguments of a constant, use + :ref:`Arguments <ArgumentScopes>`. + +.. _Abbreviations: + +Abbreviations +-------------- + +.. cmd:: {? Local} Notation @ident {+ @ident} := @term {? (only parsing)}. + + An *abbreviation* is a name, possibly applied to arguments, that + denotes a (presumably) more complex expression. Here are examples: + + .. coqtop:: none + + Require Import List. + Require Import Relations. + Set Printing Notations. + + .. coqtop:: in + + Notation Nlist := (list nat). + + .. coqtop:: all + + Check 1 :: 2 :: 3 :: nil. + + .. coqtop:: in + + Notation reflexive R := (forall x, R x x). + + .. coqtop:: all + + Check forall A:Prop, A <-> A. + Check reflexive iff. + + An abbreviation expects no precedence nor associativity, since it + is parsed as an usual application. Abbreviations are used as + much as possible by the Coq printers unless the modifier ``(only + parsing)`` is given. + + An abbreviation is bound to an absolute name as an ordinary definition is + and it also can be referred to by a qualified name. + + Abbreviations are syntactic in the sense that they are bound to + expressions which are not typed at the time of the definition of the + abbreviation but at the time they are used. Especially, abbreviations + can be bound to terms with holes (i.e. with “``_``”). For example: + + .. coqtop:: none reset + + Set Strict Implicit. + Set Printing Depth 50. + + .. coqtop:: in + + Definition explicit_id (A:Set) (a:A) := a. + + .. coqtop:: in + + Notation id := (explicit_id _). + + .. coqtop:: all + + Check (id 0). + + Abbreviations disappear when a section is closed. No typing of the + denoted expression is performed at definition time. Type checking is + done only at the time of use of the abbreviation. + +Numeral notations +----------------- + +.. cmd:: Numeral Notation @ident__1 @ident__2 @ident__3 : @scope. + :name: Numeral Notation + + This command allows the user to customize the way numeral literals + are parsed and printed. + + The token :n:`@ident__1` should be the name of an inductive type, + while :n:`@ident__2` and :n:`@ident__3` should be the names of the + parsing and printing functions, respectively. The parsing function + :n:`@ident__2` should have one of the following types: + + * :n:`Decimal.int -> @ident__1` + * :n:`Decimal.int -> option @ident__1` + * :n:`Decimal.uint -> @ident__1` + * :n:`Decimal.uint -> option @ident__1` + * :n:`Z -> @ident__1` + * :n:`Z -> option @ident__1` + * :n:`Decimal.decimal -> @ident__1` + * :n:`Decimal.decimal -> option @ident__1` + + And the printing function :n:`@ident__3` should have one of the + following types: + + * :n:`@ident__1 -> Decimal.int` + * :n:`@ident__1 -> option Decimal.int` + * :n:`@ident__1 -> Decimal.uint` + * :n:`@ident__1 -> option Decimal.uint` + * :n:`@ident__1 -> Z` + * :n:`@ident__1 -> option Z` + * :n:`@ident__1 -> Decimal.decimal` + * :n:`@ident__1 -> option Decimal.decimal` + + When parsing, the application of the parsing function + :n:`@ident__2` to the number will be fully reduced, and universes + of the resulting term will be refreshed. + + Note that only fully-reduced ground terms (terms containing only + function application, constructors, inductive type families, and + primitive integers) will be considered for printing. + + .. cmdv:: Numeral Notation @ident__1 @ident__2 @ident__3 : @scope (warning after @num). + + When a literal larger than :token:`num` is parsed, a warning + message about possible stack overflow, resulting from evaluating + :n:`@ident__2`, will be displayed. + + .. cmdv:: Numeral Notation @ident__1 @ident__2 @ident__3 : @scope (abstract after @num). + + When a literal :g:`m` larger than :token:`num` is parsed, the + result will be :n:`(@ident__2 m)`, without reduction of this + application to a normal form. Here :g:`m` will be a + :g:`Decimal.int` or :g:`Decimal.uint` or :g:`Z`, depending on the + type of the parsing function :n:`@ident__2`. This allows for a + more compact representation of literals in types such as :g:`nat`, + and limits parse failures due to stack overflow. Note that a + warning will be emitted when an integer larger than :token:`num` + is parsed. Note that :n:`(abstract after @num)` has no effect + when :n:`@ident__2` lands in an :g:`option` type. + + .. exn:: Cannot interpret this number as a value of type @type + + The numeral notation registered for :token:`type` does not support + the given numeral. This error is given when the interpretation + function returns :g:`None`, or if the interpretation is registered + only for integers or non-negative integers, and the given numeral + has a fractional or exponent part or is negative. + + + .. exn:: @ident should go from Decimal.int to @type or (option @type). Instead of Decimal.int, the types Decimal.uint or Z or Int63.int or Decimal.decimal could be used (you may need to require BinNums or Decimal or Int63 first). + + The parsing function given to the :cmd:`Numeral Notation` + vernacular is not of the right type. + + .. exn:: @ident should go from @type to Decimal.int or (option Decimal.int). Instead of Decimal.int, the types Decimal.uint or Z or Int63.int or Decimal.decimal could be used (you may need to require BinNums or Decimal or Int63 first). + + The printing function given to the :cmd:`Numeral Notation` + vernacular is not of the right type. + + .. exn:: @type is not an inductive type. + + Numeral notations can only be declared for inductive types with no + arguments. + + .. exn:: Unexpected term @term while parsing a numeral notation. + + Parsing functions must always return ground terms, made up of + applications of constructors, inductive types, and primitive + integers. Parsing functions may not return terms containing + axioms, bare (co)fixpoints, lambdas, etc. + + .. exn:: Unexpected non-option term @term while parsing a numeral notation. + + Parsing functions expected to return an :g:`option` must always + return a concrete :g:`Some` or :g:`None` when applied to a + concrete numeral expressed as a decimal. They may not return + opaque constants. + + .. exn:: Cannot interpret in @scope because @ident could not be found in the current environment. + + The inductive type used to register the numeral notation is no + longer available in the environment. Most likely, this is because + the numeral notation was declared inside a functor for an + inductive type inside the functor. This use case is not currently + supported. + + Alternatively, you might be trying to use a primitive token + notation from a plugin which forgot to specify which module you + must :g:`Require` for access to that notation. + + .. exn:: Syntax error: [prim:reference] expected after 'Notation' (in [vernac:command]). + + The type passed to :cmd:`Numeral Notation` must be a single + identifier. + + .. exn:: Syntax error: [prim:reference] expected after [prim:reference] (in [vernac:command]). + + Both functions passed to :cmd:`Numeral Notation` must be single + identifiers. + + .. exn:: The reference @ident was not found in the current environment. + + Identifiers passed to :cmd:`Numeral Notation` must exist in the + global environment. + + .. exn:: @ident is bound to a notation that does not denote a reference. + + Identifiers passed to :cmd:`Numeral Notation` must be global + references, or notations which denote to single identifiers. + + .. warn:: Stack overflow or segmentation fault happens when working with large numbers in @type (threshold may vary depending on your system limits and on the command executed). + + When a :cmd:`Numeral Notation` is registered in the current scope + with :n:`(warning after @num)`, this warning is emitted when + parsing a numeral greater than or equal to :token:`num`. + + .. warn:: To avoid stack overflow, large numbers in @type are interpreted as applications of @ident__2. + + When a :cmd:`Numeral Notation` is registered in the current scope + with :n:`(abstract after @num)`, this warning is emitted when + parsing a numeral greater than or equal to :token:`num`. + Typically, this indicates that the fully computed representation + of numerals can be so large that non-tail-recursive OCaml + functions run out of stack space when trying to walk them. + + For example + + .. coqtop:: all warn + + Check 90000. + + .. warn:: The 'abstract after' directive has no effect when the parsing function (@ident__2) targets an option type. + + As noted above, the :n:`(abstract after @num)` directive has no + effect when :n:`@ident__2` lands in an :g:`option` type. + +String notations +----------------- + +.. cmd:: String Notation @ident__1 @ident__2 @ident__3 : @scope. + :name: String Notation + + This command allows the user to customize the way strings are parsed + and printed. + + The token :n:`@ident__1` should be the name of an inductive type, + while :n:`@ident__2` and :n:`@ident__3` should be the names of the + parsing and printing functions, respectively. The parsing function + :n:`@ident__2` should have one of the following types: + + * :n:`Byte.byte -> @ident__1` + * :n:`Byte.byte -> option @ident__1` + * :n:`list Byte.byte -> @ident__1` + * :n:`list Byte.byte -> option @ident__1` + + And the printing function :n:`@ident__3` should have one of the + following types: + + * :n:`@ident__1 -> Byte.byte` + * :n:`@ident__1 -> option Byte.byte` + * :n:`@ident__1 -> list Byte.byte` + * :n:`@ident__1 -> option (list Byte.byte)` + + When parsing, the application of the parsing function + :n:`@ident__2` to the string will be fully reduced, and universes + of the resulting term will be refreshed. + + Note that only fully-reduced ground terms (terms containing only + function application, constructors, inductive type families, and + primitive integers) will be considered for printing. + + .. exn:: Cannot interpret this string as a value of type @type + + The string notation registered for :token:`type` does not support + the given string. This error is given when the interpretation + function returns :g:`None`. + + .. exn:: @ident should go from Byte.byte or (list Byte.byte) to @type or (option @type). + + The parsing function given to the :cmd:`String Notation` + vernacular is not of the right type. + + .. exn:: @ident should go from @type to Byte.byte or (option Byte.byte) or (list Byte.byte) or (option (list Byte.byte)). + + The printing function given to the :cmd:`String Notation` + vernacular is not of the right type. + + .. exn:: @type is not an inductive type. + + String notations can only be declared for inductive types with no + arguments. + + .. exn:: Unexpected term @term while parsing a string notation. + + Parsing functions must always return ground terms, made up of + applications of constructors, inductive types, and primitive + integers. Parsing functions may not return terms containing + axioms, bare (co)fixpoints, lambdas, etc. + + .. exn:: Unexpected non-option term @term while parsing a string notation. + + Parsing functions expected to return an :g:`option` must always + return a concrete :g:`Some` or :g:`None` when applied to a + concrete string expressed as a decimal. They may not return + opaque constants. + + .. exn:: Cannot interpret in @scope because @ident could not be found in the current environment. + + The inductive type used to register the string notation is no + longer available in the environment. Most likely, this is because + the string notation was declared inside a functor for an + inductive type inside the functor. This use case is not currently + supported. + + Alternatively, you might be trying to use a primitive token + notation from a plugin which forgot to specify which module you + must :g:`Require` for access to that notation. + + .. exn:: Syntax error: [prim:reference] expected after 'Notation' (in [vernac:command]). + + The type passed to :cmd:`String Notation` must be a single + identifier. + + .. exn:: Syntax error: [prim:reference] expected after [prim:reference] (in [vernac:command]). + + Both functions passed to :cmd:`String Notation` must be single + identifiers. + + .. exn:: The reference @ident was not found in the current environment. + + Identifiers passed to :cmd:`String Notation` must exist in the + global environment. + + .. exn:: @ident is bound to a notation that does not denote a reference. + + Identifiers passed to :cmd:`String Notation` must be global + references, or notations which denote to single identifiers. + +.. _TacticNotation: + +Tactic Notations +----------------- + +Tactic notations allow to customize the syntax of tactics. They have the following syntax: + +.. productionlist:: coq + tacn : Tactic Notation [`tactic_level`] [`prod_item` … `prod_item`] := `tactic`. + prod_item : `string` | `tactic_argument_type`(`ident`) + tactic_level : (at level `num`) + tactic_argument_type : `ident` | `simple_intropattern` | `reference` + : `hyp` | `hyp_list` | `ne_hyp_list` + : `constr` | `uconstr` | `constr_list` | `ne_constr_list` + : `integer` | `integer_list` | `ne_integer_list` + : `int_or_var` | `int_or_var_list` | `ne_int_or_var_list` + : `tactic` | `tactic0` | `tactic1` | `tactic2` | `tactic3` + : `tactic4` | `tactic5` + +.. cmd:: Tactic Notation {? (at level @level)} {+ @prod_item} := @tactic. + + A tactic notation extends the parser and pretty-printer of tactics with a new + rule made of the list of production items. It then evaluates into the + tactic expression ``tactic``. For simple tactics, it is recommended to use + a terminal symbol, i.e. a string, for the first production item. The + tactic level indicates the parsing precedence of the tactic notation. + This information is particularly relevant for notations of tacticals. + Levels 0 to 5 are available (default is 5). + + .. cmd:: Print Grammar tactic + + To know the parsing precedences of the existing tacticals, use the command + ``Print Grammar tactic``. + + Each type of tactic argument has a specific semantic regarding how it + is parsed and how it is interpreted. The semantic is described in the + following table. The last command gives examples of tactics which use + the corresponding kind of argument. + + .. list-table:: + :header-rows: 1 + + * - Tactic argument type + - parsed as + - interpreted as + - as in tactic + + * - ``ident`` + - identifier + - a user-given name + - intro + + * - ``simple_intropattern`` + - intro_pattern + - an intro pattern + - intros + + * - ``hyp`` + - identifier + - a hypothesis defined in context + - clear + + * - ``reference`` + - qualified identifier + - a global reference of term + - unfold + + * - ``constr`` + - term + - a term + - exact + + * - ``uconstr`` + - term + - an untyped term + - refine + + * - ``integer`` + - integer + - an integer + - + + * - ``int_or_var`` + - identifier or integer + - an integer + - do + + * - ``tactic`` + - tactic at level 5 + - a tactic + - + + * - ``tacticn`` + - tactic at level n + - a tactic + - + + * - *entry*\ ``_list`` + - list of *entry* + - a list of how *entry* is interpreted + - + + * - ``ne_``\ *entry*\ ``_list`` + - non-empty list of *entry* + - a list of how *entry* is interpreted + - + + .. note:: In order to be bound in tactic definitions, each syntactic + entry for argument type must include the case of a simple |Ltac| + identifier as part of what it parses. This is naturally the case for + ``ident``, ``simple_intropattern``, ``reference``, ``constr``, ... but not for ``integer``. + This is the reason for introducing a special entry ``int_or_var`` which + evaluates to integers only but which syntactically includes + identifiers in order to be usable in tactic definitions. + + .. note:: The *entry*\ ``_list`` and ``ne_``\ *entry*\ ``_list`` entries can be used in + primitive tactics or in other notations at places where a list of the + underlying entry can be used: entry is either ``constr``, ``hyp``, ``integer`` + or ``int_or_var``. + +.. cmdv:: Local Tactic Notation + + Tactic notations disappear when a section is closed. They survive when + a module is closed unless the command ``Local Tactic Notation`` is used instead + of :cmd:`Tactic Notation`. + +.. rubric:: Footnotes + +.. [#and_or_levels] which are the levels effectively chosen in the current + implementation of Coq + +.. [#no_associativity] Coq accepts notations declared as nonassociative but the parser on + which Coq is built, namely Camlp5, currently does not implement ``no associativity`` and + replaces it with ``left associativity``; hence it is the same for Coq: ``no associativity`` + is in fact ``left associativity`` for the purposes of parsing diff --git a/doc/sphinx/zebibliography.html.rst b/doc/sphinx/zebibliography.html.rst new file mode 100644 index 0000000000..756edd5482 --- /dev/null +++ b/doc/sphinx/zebibliography.html.rst @@ -0,0 +1,17 @@ +.. There are multiple issues with sphinxcontrib-bibtex that we have to work around: + - The list of cited entries is computed right after encountering + `.. bibliography`, so the file containing that command has to come last + alphabetically: + https://sphinxcontrib-bibtex.readthedocs.io/en/latest/usage.html#unresolved-citations-across-documents + - `.. bibliography::` puts the bibliography on its own page with its own + title in LaTeX, but includes it inline without a title in HTML: + https://sphinxcontrib-bibtex.readthedocs.io/en/latest/usage.html#mismatch-between-output-of-html-and-latex-backends + +.. _bibliography: + +============== + Bibliography +============== + +.. bibliography:: biblio.bib + :cited: diff --git a/doc/sphinx/zebibliography.latex.rst b/doc/sphinx/zebibliography.latex.rst new file mode 100644 index 0000000000..2c0396f1c9 --- /dev/null +++ b/doc/sphinx/zebibliography.latex.rst @@ -0,0 +1,6 @@ +.. See zebibliography.html.rst for details + +.. _bibliography: + +.. bibliography:: biblio.bib + :cited: |
