diff options
Diffstat (limited to 'doc/sphinx/proof-engine')
| -rw-r--r-- | doc/sphinx/proof-engine/proof-handling.rst | 592 | ||||
| -rw-r--r-- | doc/sphinx/proof-engine/ssreflect-proof-language.rst | 102 | ||||
| -rw-r--r-- | doc/sphinx/proof-engine/tactics.rst | 2 | ||||
| -rw-r--r-- | doc/sphinx/proof-engine/vernacular-commands.rst | 1414 |
4 files changed, 2058 insertions, 52 deletions
diff --git a/doc/sphinx/proof-engine/proof-handling.rst b/doc/sphinx/proof-engine/proof-handling.rst new file mode 100644 index 0000000000..52cde52c69 --- /dev/null +++ b/doc/sphinx/proof-engine/proof-handling.rst @@ -0,0 +1,592 @@ +.. include:: ../replaces.rst +.. _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. He 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`. +When switching in editing proof mode, the prompt ``Coq <`` is changed into +``ident <`` where ``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:`TODO_gallina_assumptions`) +and the local variables and hypotheses of the theorem statement. It is +enriched by the use of certain tactics (see e.g. ``intro`` in Section +:ref:`managingthelocalcontext`). + +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* [[How80]_, +[Bar81]_, [Gir89]_, [Hue88]_ ], |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. + +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: + +.. cmd:: Theorem @ident [@binders] : @form. + +The list of assertion commands is given in Section :ref:TODO-assertions_and_proof`. The +command ``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 ``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 + +.. 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. + +Defines the proved term as a transparent constant. + +.. cmdv:: Save @ident. + +Forces the name of the original goal to be :n:`@ident`. This +command (and the following ones) can only be used if the original goal +has been opened using the ``Goal`` command. + + +.. cmd:: Admitted. + +This command is available in interactive editing proof mode to give up +the current proof and declare the initial goal as an axiom. + + +.. cmd:: Proof @term. + +This command applies in proof editing mode. It is equivalent to + +.. cmd:: exact @term. Qed. + +That is, you have to give the full proof in one gulp, as a +proof term (see Section :ref:`applyingtheorems`). + + +.. cmdv:: Proof. + +Is a noop which is useful to delimit the sequence of tactic commands +which start a proof, after a ``Theorem`` command. It is a good practice to +use ``Proof``. as an opening parenthesis, closed in the script with a +closing ``Qed``. + + +See also: ``Proof with tactic.`` in Section +:ref:`setimpautotactics`. + + +.. cmd:: Proof using @ident1 ... @identn. + +This command applies in proof editing mode. It declares the set of +section variables (see :ref:`TODO-gallina-assumptions`) used by the proof. At ``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 variable and a is a variable of type ``T``, the commands +``Proof using a`` and ``Proof using T a``` are actually equivalent. + + +.. cmdv:: Proof using @ident1 ... @identn with @tactic. + +in Section :ref:`setimpautotactics`. + +.. cmdv:: Proof using All. + +Use all section variables. + + +.. cmdv:: Proof using Type. + +.. cmdv:: Proof using. + +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 -(@ident1 ... @identn). + +Use all section variables except :n:`@ident1` ... :n:`@identn`. + + +.. cmdv:: Proof using @collection1 + @collection2 . + + +.. cmdv:: Proof using @collection1 - @collection2 . + + +.. cmdv:: Proof using @collection - ( @ident1 ... @identn ). + + +.. cmdv:: Proof using @collection * . + +Use section variables being, respectively, in the set union, set +difference, set complement, set forward transitive closure. See +Section :ref:`nameaset` to know how to form a named collection. The ``*`` operator +binds stronger than ``+`` and ``-``. + + +Proof using options +``````````````````` + +The following options modify the behavior of ``Proof using``. + + +.. cmdv:: Set Default Proof Using "@expression". + +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``. + + +.. cmdv:: Set Suggest Proof Using. + +When ``Qed`` is performed, suggest a using annotation if the user did not +provide one. + +.. _`nameaset`: + +Name a set of section hypotheses for ``Proof using`` +```````````````````````````````````````````````````` + +The command ``Collection`` can be used to name a set of section +hypotheses, with the purpose of making ``Proof using`` annotations more +compact. + + +.. cmdv:: Collection Some := x y z. + +Define the collection named "Some" containing ``x``, ``y`` and ``z``. + + +.. cmdv:: Collection Fewer := Some - z. + +Define the collection named "Fewer" containing only ``x`` and ``y``. + + +.. cmdv:: Collection Many := Fewer + Some. +.. cmdv:: Collection Many := Fewer - Some. + +Define the collection named "Many" containing the set union or set +difference of "Fewer" and "Some". + + +.. cmdv:: Collection Many := Fewer - (x y). + +Define the collection named "Many" containing the set difference of +"Fewer" and the unnamed collection ``x`` ``y``. + + +.. 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) + + + +.. cmdv:: Abort @ident. + +Aborts the editing of the proof named :n:`@ident`. + +.. cmdv:: Abort All. + +Aborts all current goals, switching back to the |Coq| +toplevel. + + + +.. cmd:: Existential @num := @term. + +This command instantiates an existential variable. :n:`@num` is an index in +the list of uninstantiated existential variables displayed by ``Show +Existentials`` (described in Section :ref:`requestinginformation`). + +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 instantiate. + + +See also: ``instantiate (num:= term).`` in Section +:ref:`TODO-controllingtheproofflow`. +See also: ``Grab Existential Variables.`` below. + + +.. 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 :n:`@num` times. + +.. cmdv:: Restart. + +This command restores the proof editing process to the original goal. + + +.. exn:: No focused proof to restart + + +.. 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. + + +.. cmdv:: Focus @num. + +This focuses the attention on the :n:`@num` th subgoal to +prove. + +*This command is deprecated since 8.8*: prefer the use of bullets or +focusing brackets instead, including :n:`@num : %{` + +.. cmd:: Unfocus. + +This command restores to focus the goal that were suspended by the +last ``Focus`` command. + +*This command is deprecated since 8.8.* + +.. cmd:: Unfocused. + +Succeeds if the proof is fully unfocused, fails is there are some +goals out of focus. + + +.. cmd:: %{ %| %} + +The command ``{`` (without a terminating period) focuses on the first +goal, much like ``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 example in 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 :n:`@num` th subgoal to prove. + +Error messages: + +.. 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 + +.. exn:: Brackets only support the single numbered goal selector + + +See also error messages about bullets below. + +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. Available bullets +are ``-``, ``+``, ``*``, ``--``, ``++``, ``**``, ``---``, ``+++``, ``***``, ... (without a terminating period). + +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. + + +.. exn:: Wrong bullet @bullet1 : Current bullet @bullet2 is not finished. + +Before using bullet :n:`@bullet1` again, you should first finish proving the current focused goal. Note that :n:`@bullet1` and :n:`@bullet2` may be the same. + +.. exn:: Wrong bullet @bullet1 : Bullet @bullet2 is mandatory here. + +You must put :n:`@bullet2` to focus next goal. No other bullet is allowed here. + +.. exn:: No such goal. Focus next goal with bullet @bullet. + +You tried to applied a tactic but no goal where under focus. Using :n:`@bullet` is mandatory here. + +.. exn:: No such goal. Try unfocusing with %{. + +You just finished a goal focused by ``{``, you must unfocus it with ``}``. + +Set Bullet Behavior +``````````````````` + +The bullet behavior can be controlled by the following commands. + +.. opt:: Bullet Behavior "None". + +This makes bullets inactive. + +.. opt:: Bullet Behavior "Strict Subproofs". + +This makes bullets active (this is the default behavior). + + + +Requesting information +---------------------- + + +.. cmd:: Show. + +This command displays the current goals. + + +.. cmdv:: Show @num + +Displays only the :n:`@num`-th subgoal. + +.. exn:: No such goal +.. exn:: No focused proof + +.. cmdv:: Show @ident. + +Displays the named goal :n:`@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:`exvariables`) as in the following example. + +.. example:: + + .. coqtop:: all + + Goal exists n, n = 0. + eexists ?[n]. + Show n. + +.. cmdv:: 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>``. + +.. cmdv:: 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 hole-placer are also printed. + +.. cmdv:: 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. + +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 ``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 ``intro`` +into a qualified one such as ``intro y13``. In the case of a non-product +goal, it prints nothing. + +.. cmdv:: Show Intros. + +This command is similar to the previous one, it +simulates the naming process of an intros. + +.. cmdv:: 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 +:n:`@ident` + +.. example:: + .. coqtop:: all + + Show Match nat. + +.. exn:: Unknown inductive type + +.. exn:: 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. refine :ref:`applyingtheorems`) 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 ``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. + + +Controlling the effect of proof editing commands +------------------------------------------------ + + +.. opt:: Hyps Limit @num. + +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. + + +.. opt:: Automatic Introduction. + +This option controls the way binders are handled +in assertion commands such as ``Theorem ident [binders] : form``. When the +option is set, which is the default, binders are automatically put in +the local context of the goal to prove. + +The option can be unset by issuing ``Unset Automatic Introduction``. When +the option is unset, binders are discharged on the statement to be +proved and a tactic such as intro (see Section :ref:`managingthelocalcontext`) has to be +used to move the assumptions to the local context. + + +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 ``optimize_heap`` (see~:ref:`tactic-optimizeheap`) diff --git a/doc/sphinx/proof-engine/ssreflect-proof-language.rst b/doc/sphinx/proof-engine/ssreflect-proof-language.rst index 61dffa0243..bd71e5ed81 100644 --- a/doc/sphinx/proof-engine/ssreflect-proof-language.rst +++ b/doc/sphinx/proof-engine/ssreflect-proof-language.rst @@ -451,7 +451,7 @@ Anonymous arguments ~~~~~~~~~~~~~~~~~~~ When in a definition, the type of a certain argument is mandatory, but -not its name, one usually use “arrow” abstractions for prenex +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 @@ -518,7 +518,7 @@ 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 ``pose`` supoprts parameters: +global ones. For example, the tactic ``pose`` supoprts parameters: .. example:: @@ -1295,7 +1295,7 @@ is a synonym for: intro top; first [refine top | refine (top _) | refine (top _ _) | …]; clear top. -where ``top`` is fresh name, and the sequence of refine tactics tries to +where ``top`` is a fresh name, and the sequence of refine tactics tries to catch the appropriate number of wildcards to be inserted. Note that this use of the refine tactic implies that the tactic tries to match the goal up to expansion of constants and evaluation of subterms. @@ -1573,7 +1573,7 @@ The :token:`i_pattern` s can be seen as a variant of *intro patterns* :ref:`tactics`: each performs an introduction operation, i.e., pops some variables or assumptions from the goal. -An :token:`s_item` can simplify the set of subgoals or the subgoal themselves: +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 ``done`` described in :ref:`terminators_ssr`, i.e., @@ -1831,7 +1831,7 @@ compact syntax: case: {2}_ / eqP. -were ``_`` is interpreted as ``(_ == _)`` since +where ``_`` is interpreted as ``(_ == _)`` since ``eqP T a b : reflect (a = b) (a == b)`` and reflect is a type family with one index. @@ -2074,7 +2074,7 @@ is equivalent to: do [done | by move=> top; apply top]. -where top is a fresh name affected to the top assumption of the goal. +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: @@ -2090,7 +2090,7 @@ is equivalent to: (see section :ref:`discharge_ssr` for the documentation of the apply: combination). -Warning The list of tactics, possibly chained by semi-columns, that +Warning The list of tactics, possibly chained by semicolons, that follows a by keyword is considered as a parenthesized block applied to the current goal. Hence for example if the tactic: @@ -2123,7 +2123,7 @@ 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 an other powerful way of linearization of scripts, since it +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, the tactic: @@ -2131,14 +2131,14 @@ one line tactic. For instance, the tactic: :name: last tries to solve the last subgoal generated by the first -tactic using the given second tactic , and fails if it does not succeeds. -Its analogous +tactic using the given second tactic, and fails if it does not succeed. +Its analogue .. tacn:: @tactic ; first by @tactic :name: first tries to solve the first subgoal generated by the first tactic using the -second given tactic, and fails if it does not succeeds. +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. The tactic: @@ -2259,14 +2259,14 @@ For instance, the tactic: tactic; do 1? rewrite mult_comm. -rewrites at most one time the lemma ``mult_com`` in all the subgoals +rewrites at most one time the lemma ``mult_comm`` in all the subgoals generated by tactic , whereas the tactic: .. coqtop:: in tactic; do 2! rewrite mult_comm. -rewrites exactly two times the lemma ``mult_com`` in all the subgoals +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. @@ -2335,10 +2335,10 @@ to the following one: .. tacv:: @tactic in {+ @clear_switch | {? @ } @ident | ( @ident ) | ( {? @ } @ident := @c_pattern ) } {? * } In its simplest form the last option lets one rename hypotheses that -can’t be cleared (like section variables). For example ``(y := x)`` +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 this form of localization refer +For a more precise description of this form of localization refer to :ref:`advanced_generalization_ssr`. @@ -2351,7 +2351,7 @@ 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) -text book proof. +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 @@ -2492,7 +2492,7 @@ also supported (assuming x occurs in the goal only): have {x} -> : x = y. -An other frequent use of the intro patterns combined with ``have`` is the +Another frequent use of the intro patterns combined with ``have`` is the destruction of existential assumptions like in the tactic: .. example:: @@ -2845,8 +2845,8 @@ term -> G. If the optional list of :token:`itent` is present on the left side of ``/``, these constants are generalized in the -premise (term -> G) of the first subgoal. By default the body of local -definitions is erased. This behavior can be inhibited prefixing 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: @@ -2936,7 +2936,7 @@ 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 cover the case of both local and global definitions, as +unfolded. This covers the case of both local and global definitions, as illustrated in the following example. .. example:: @@ -3035,7 +3035,7 @@ operation should be performed: 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 an other term, according to the + 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 @@ -3329,7 +3329,7 @@ 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 iterates the +multiplier switches, which makes the rewrite tactic iterate the rewrite operations prescribed by the rules on the current goal. @@ -3473,7 +3473,7 @@ 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 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 @@ -3736,8 +3736,8 @@ replaces the occurrence(s) of :token:`ident` coded by the 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 an -other mechanism of term tagging, resting on the following *Notation*: +allowed the evaluation of a condition. This is possible thanks to another +mechanism of term tagging, resting on the following *Notation*: .. coqtop:: in @@ -3781,7 +3781,7 @@ arithmetic operations. We define for instance: 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 inter-convertible). +``(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. @@ -3792,7 +3792,7 @@ essentially invisible. Congruence ~~~~~~~~~~ -Because of the way matching interferes with type families parameters, +Because of the way matching interferes with parameters of type families, the tactic: .. coqtop:: in @@ -3912,8 +3912,8 @@ 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 functions arguments. These copies usually end up in -types hidden by the implicit arguments machinery or by user defined +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 Printing All flag. Moreover the resulting script is @@ -3981,7 +3981,7 @@ pattern for the redex looking at the rule used for rewriting. 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 mean of redex +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 @@ -4064,7 +4064,7 @@ 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 for of :token:`c_pattern`. To void confusion in the grammar, open +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. @@ -4086,17 +4086,17 @@ parentheses are required around more complex patterns. set t := (a + _ in X in _ = X). -Since the user may define an infix notation for ``in`` the former tactic -may result ambiguous. The disambiguation rule implemented is to prefer +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 +parentheses as a simple term. For example, the following tactic would capture any occurrence of the term ``a in A``. .. coqtop:: in set t := ((a in A)). -Contextual pattern can also be used as arguments of the ``:`` tactical. +Contextual patterns can also be used as arguments of the ``:`` tactical. For example: .. coqtop:: in @@ -4139,7 +4139,7 @@ Contextual patterns in rewrite 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``, ``0`` here. + of ``addn0`` is unified with the term identified by ``X``, here ``0``. The following pattern does not specify a redex, since it identifies an @@ -4269,7 +4269,7 @@ generation (see section :ref:`generation_of_equations_ssr`). .. example:: - The following script illustrate a toy example of this feature. Let us + 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 @@ -4283,7 +4283,7 @@ generation (see section :ref:`generation_of_equations_ssr`). .. coqtop:: all Variable d : Type. - Fixpoint add_last(s : list d) (z : d) {struct s} : list d := + 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 @@ -4296,7 +4296,7 @@ generation (see section :ref:`generation_of_equations_ssr`). 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 + in a concise syntax for reasoning inductively using the user-defined elimination scheme. .. coqtop:: all @@ -4305,8 +4305,8 @@ generation (see section :ref:`generation_of_equations_ssr`). elim/last_ind_list E : l=> [| u v]; last first. -User provided eliminators (potentially generated with the ``Function`` -|Coq|’s command) can be combined with the type family switches described +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: @@ -4341,7 +4341,7 @@ The ``elim/`` tactic distinguishes two cases: As explained in section :ref:`type_families_ssr`, the initial prefix of ``ei`` can be omitted. -Here an example of a regular, but non trivial, eliminator. +Here is an example of a regular, but nontrivial, eliminator. .. example:: @@ -4423,7 +4423,7 @@ Here an example of a regular, but non trivial, eliminator. ``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 an example of a truncated eliminator: +Here is an example of a truncated eliminator: .. example:: @@ -4481,7 +4481,7 @@ Interpreting assumptions ~~~~~~~~~~~~~~~~~~~~~~~~ Interpreting an assumption in the context of a proof consists in -applying it a lemma before generalizing, and/or decomposing this +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 @@ -4689,7 +4689,7 @@ the bookkeeping tactical ``=>`` since this would be redundant with the Boolean reflection ~~~~~~~~~~~~~~~~~~ -In the Calculus of Inductive Construction, there is an obvious +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 @@ -5002,7 +5002,7 @@ but they also allow complex transformation, involving negations. 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 used its propositional interpretation. +actually uses its propositional interpretation. .. example:: @@ -5038,7 +5038,7 @@ applied to a goal ``top`` is interpreted in the following way: Like assumption interpretation view hints, goal interpretation ones -are user defined lemmas stored (see section :ref:`views_and_reflection_ssr`) in the ``Hint View`` +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. @@ -5132,7 +5132,7 @@ See the files ``ssreflect.v`` and ``ssrbool.v`` for examples. Multiple views ~~~~~~~~~~~~~~ -The hypotheses and the goal can be interpreted applying 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 @@ -5189,7 +5189,7 @@ equivalences are indeed taken into account, otherwise only single .. cmd:: Search {? @pattern } {* {? - } %( @string %| @pattern %) {? % @ident} } {? in {+ {? - } @qualid } } -where :token:`qualid` is the name of an open module. This command search returns +where :token:`qualid` is the name of an open module. This command returns the list of lemmas: @@ -5214,7 +5214,7 @@ Note that: + As for regular terms, patterns can feature scope indications. For instance, the command: ``Search _ (_ + _)%N.`` lists all the lemmas whose - statement (conclusion or hypotheses) involve an application of the + 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. @@ -5491,7 +5491,7 @@ prenex implicits declaration see :ref:`parametric_polymorphism_ssr` 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 not such obstruction +.. [#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. diff --git a/doc/sphinx/proof-engine/tactics.rst b/doc/sphinx/proof-engine/tactics.rst index da34e3b55b..2af73c28e5 100644 --- a/doc/sphinx/proof-engine/tactics.rst +++ b/doc/sphinx/proof-engine/tactics.rst @@ -1635,7 +1635,7 @@ analysis on inductive or co-inductive objects (see :ref:`TODO-4.5`). .. tacv:: elim @term using @term .. tacv:: elim @term using @term with @bindings_list - Allows the user to give explicitly an elimination predicate :n:`@term` that + 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`. diff --git a/doc/sphinx/proof-engine/vernacular-commands.rst b/doc/sphinx/proof-engine/vernacular-commands.rst new file mode 100644 index 0000000000..0bb6eea233 --- /dev/null +++ b/doc/sphinx/proof-engine/vernacular-commands.rst @@ -0,0 +1,1414 @@ +.. include:: ../preamble.rst +.. include:: ../replaces.rst + +.. _vernacularcommands: + +Vernacular commands +============================= + +.. _displaying: + +Displaying +-------------- + + +.. _Print: + +.. cmd:: Print @qualid. + +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 + +.. exn:: Universe instance should have length :n:`num`. + +.. exn:: This object does not support universe names. + + +Variants: + + +.. cmdv:: Print Term @qualid. + +This is a synonym to ``Print`` :n:`@qualid` when :n:`@qualid` +denotes a global constant. + +.. cmdv:: About @qualid. + +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:: Print @qualid\@@name + +This locally renames the polymorphic universes of :n:`@qualid`. +An underscore means the raw universe is printed. +This form can be used with ``Print Term`` and ``About``. + +.. cmd:: Print All. + +This command displays information about the current state of the +environment, including sections and modules. + + +Variants: + + +.. cmdv:: Inspect @num. + +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| configurability is based on flags (e.g. Set Printing All in +Section :ref:`TODO-2.9-printing-full`), options (e.g. ``Set Printing Widthinteger`` in Section +:ref:`TODO-6.9.6-set-printing-width`), or tables (e.g. ``Add Printing Record ident``, in Section +:ref:`TODO-2.2.4-add-printing-record`). The names of flags, options and tables are made of non-empty sequences of identifiers +(conventionally with capital initial +letter). The general commands handling flags, options and tables are +given below. + +.. TODO : flag is not a syntax entry + +.. cmd:: Set @flag. + +This command switches :n:`@flag` on. The original state of :n:`@flag` is restored +when the current module ends. + + +Variants: + + +.. cmdv:: Local Set @flag. + +This command switches :n:`@flag` on. The original state +of :n:`@flag` is restored when the current *section* ends. + +.. cmdv:: Global Set @flag. + +This command switches :n:`@flag` on. The original state +of :n:`@flag` is *not* restored at the end of the module. Additionally, if +set in a file, :n:`@flag` is switched on when the file is `Require`-d. + + + +.. cmd:: Unset @flag. + +This command switches :n:`@flag` off. The original state of :n:`@flag` is restored +when the current module ends. + + +Variants: + +.. cmdv:: Local Unset @flag. + +This command switches :n:`@flag` off. The original +state of :n:`@flag` is restored when the current *section* ends. + +.. cmdv:: Global Unset @flag. + +This command switches :n:`@flag` off. The original +state of :n:`@flag` is *not* restored at the end of the module. Additionally, +if set in a file, :n:`@flag` is switched off when the file is `Require`-d. + + + +.. cmd:: Test @flag. + +This command prints whether :n:`@flag` is on or off. + + +.. cmd:: Set @option @value. + +This command sets :n:`@option` to :n:`@value`. The original value of ` option` is +restored when the current module ends. + + +Variants: + +.. TODO : option and value are not syntax entries + +.. cmdv:: Local Set @option @value. + +This command sets :n:`@option` to :n:`@value`. The +original value of :n:`@option` is restored at the end of the module. + +.. cmdv:: Global Set @option @value. + +This command sets :n:`@option` to :n:`@value`. The +original value of :n:`@option` is *not* restored at the end of the module. +Additionally, if set in a file, :n:`@option` is set to value when the file +is `Require`-d. + + + +.. cmd:: Unset @option. + +This command resets option to its default value. + + +Variants: + + +.. cmdv:: Local Unset @option. + +This command resets :n:`@option` to its default +value. The original state of :n:`@option` is restored when the current +*section* ends. + +.. cmdv:: Global Unset @option. + +This command resets :n:`@option` to its default +value. The original state of :n:`@option` is *not* restored at the end of the +module. Additionally, if unset in a file, :n:`@option` is reset to its +default value when the file is `Require`-d. + + + +.. cmd:: Test @option. + +This command prints the current value of :n:`@option`. + + +.. TODO : table is not a syntax entry + +.. cmd:: Add @table @value. +.. cmd:: Remove @table @value. +.. cmd:: Test @table @value. +.. cmd:: Test @table for @value. +.. cmd:: Print Table @table. + +These are general commands for tables. + +.. cmd:: Print Options. + +This command lists all available flags, options and tables. + + +Variants: + + +.. cmdv:: Print Tables. + +This is a synonymous of ``Print Options``. + + +.. _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. + + +Variants: + +.. TODO : selector is not a syntax entry + +.. cmdv:: @selector: Check @term. + +specifies on which subgoal to perform typing +(see Section :ref:`TODO-8.1-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). + + +See also: Section :ref:`TODO-8.7-performing-computations`. + + +.. 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`. + + +See also: Section :ref:`TODO-8.7-performing-computations`. + + +.. cmd::Extraction @term. + +This command displays the extracted term from :n:`@term`. The extraction is +processed according to the distinction between ``Set`` and ``Prop``; that is +to say, between logical and computational content (see Section +:ref:`TODO-4.1.1-sorts`). The extracted term is displayed in OCaml +syntax, +where global identifiers are still displayed as in |Coq| terms. + + +Variants: + + +.. cmdv:: Recursive Extraction {+ @qualid }. + +Recursively extracts all +the material needed for the extraction of the qualified identifiers. + + +See also: Chapter ref:`TODO-23-chapter-extraction`. + + +.. 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. + + +Variants: + + +.. cmdv:: Print Opaque Dependencies @qualid. + +Displays the set of opaque constants :n:`@qualid` relies on in addition to +the assumptions. + +.. cmdv:: Print Transparent Dependencies @qualid. + +Displays the set of +transparent constants :n:`@qualid` relies on in addition to the assumptions. + +.. cmdv:: Print All Dependencies @qualid. + +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. + + +Error messages: + + +.. exn:: The reference @qualid was not found in the current environment + +There is no constant in the environment named qualid. + +Variants: + +.. 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:`TODO-12.1-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:`TODO-12.2.2-local-interpretation-rules-for-notations`). + +.. cmdv:: Search @term_pattern. + +This searches for all statements or types of +definition that contains a subterm that matches the pattern +`term_pattern` (holes of the pattern are either denoted by `_` or by +`?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:`TODO-8.1-invocation-of-tactics`). +By default the 1st goal is searched. This variant can +be combined with other variants presented here. + + +.. 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. + +.. note:: Up to |Coq| version 8.4, ``Search`` had the behavior of current +``SearchHead`` and the behavior of current Search was obtained with +command ``SearchAbout``. For compatibility, the deprecated name +SearchAbout can still be used as a synonym of Search. For +compatibility, the list of objects to search when using ``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. + + + +.. coqtop:: reset all + + SearchHead le. + + SearchHead (@eq bool). + + +Variants: + +.. 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. + +Error messages: + +.. exn:: Module/section @qualid not found + +No module :n:`@qualid` has been required +(see Section :ref:`TODO-6.5.1-require`). + +.. cmdv:: @selector: SearchHead @term. + +This specifies the goal on which to +search hypothesis (see Section :ref:`TODO-8.1-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 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. + +.. 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`. + + +.. coqtop:: all + + SearchPattern (?X1 + _ = _ + ?X1). + +Variants: + + +.. 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:`TODO-8.1-invocation-of-tactics`). By default the 1st goal is +searched. This variant can be combined with other variants presented +here. + + + +.. cmdv:: 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 “_”. + +.. coqtop:: in + + Require Import Arith. + +.. coqtop:: all + + SearchRewrite (_ + _ + _). + +Variants: + + +.. 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:`TODO-8.1-invocation-of-tactics`). By default the 1st goal is +searched. This variant can be combined with other variants presented +here. + +.. note:: + + For the ``Search``, ``SearchHead``, ``SearchPattern`` and ``SearchRewrite`` + queries, it + is possible to globally filter the search results via the command + ``Add Search Blacklist`` :n:`@substring`. A lemma whose fully-qualified name + contains any of the declared substrings will be removed from the + search results. The default blacklisted substrings are ``_subproof`` + ``Private_``. The command ``Remove Search Blacklist ...`` allows expunging + this blacklist. + + +.. 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 name spaces of |Coq|: terms, modules, Ltac, etc. + +.. coqtop:: none + + Set Printing Depth 50. + +.. coqtop:: all + + Locate nat. + + Locate Datatypes.O. + + Locate Init.Datatypes.O. + + Locate Coq.Init.Datatypes.O. + + Locate I.Dont.Exist. + +Variants: + + +.. 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. + + +See also: Section :ref:`TODO-12.1.10-LocateSymbol` + + +.. _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:`TODO-2.6.3-libraries-and-filesystem`) + +Files loaded this way cannot leave proofs open, and the ``Load`` +command cannot be used inside a proof either. + +Variants: + + +.. 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. + +.. cmdv:: Load Verbose @string. + +Display, while loading, +the answers of |Coq| to each command (including tactics) contained in +the loaded file See also: Section :ref:`TODO-6.9.1-silent`. + +Error messages: + +.. exn:: Can’t find file @ident on loadpath + +.. exn:: Load is not supported inside proofs + +.. exn:: Files processed by Load cannot leave open proofs + +.. _compiled-files: + +Compiled files +------------------ + +This section describes the commands used to load compiled files (see +Chapter :ref:`TODO-14-coq-commands` 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 +``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 `dirpath.ident` and the file `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:`TODO-2.6.3-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. + + +Variants: + +.. cmdv:: Require Import @qualid. + +This loads and declares the module :n:`@qualid` +and its dependencies then imports the contents of :n:`@qualid` as described +in Section :ref:`TODO-2.5.8-import`.It does not import the modules on which +qualid depends unless these modules were themselves required in module +:n:`@qualid` +using ``Require Export``, as described below, or recursively required +through a sequence of ``Require Export``. If the module required has +already been loaded, ``Require Import`` :n:`@qualid` simply imports it, as ``Import`` +:n:`@qualid` would. + +.. cmdv:: Require Export @qualid. + +This command acts as ``Require Import`` :n:`@qualid`, +but if a further module, say `A`, contains a command ``Require Export`` `B`, +then the command ``Require Import`` `A` also imports the module `B.` + +.. cmdv:: Require [Import | Export] {+ @qualid }. + +This loads the +modules named by the :n:`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 ``Require``, but picks +any library whose absolute name is of the form dirpath.dirpath’.qualid +for some `dirpath’`. This is useful to ensure that the :n:`@qualid` library +comes from a given package by making explicit its absolute root. + + + +Error messages: + +.. exn:: Cannot load qualid: no physical path bound to dirpath + +.. 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:`TODO-2.6.3-libraries-and-filesystem`). + +.. exn:: Compiled library ident.vo makes inconsistent assumptions over library qualid + +The command tried to load library file `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 `ident.v` was +not properly recompiled with the last version of the file containing +module :n:`@qualid`. + +.. exn:: Bad magic number + +The file `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 `ident.vo` contains library dirpath and not library dirpath’ + +The library file `dirpath’` is indirectly required by the +``Require`` command but it is bound in the current loadpath to the +file `ident.vo` which was bound to a different library name `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:`TODO-2.5.8-import`). + + + +See also: Chapter :ref:`TODO-14-coq-commands` + + +.. 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 :n:`@string` sequence +(dynamic link). It is mainly used to load tactics dynamically. The +files are searched into the current OCaml loadpath (see the +command ``Add ML Path`` in Section :ref:`TODO-2.6.3-libraries-and-filesystem`). Loading of OCaml files is only possible under the bytecode version of ``coqtop`` (i.e. +``coqtop`` called with option ``-byte``, see chapter :ref:`TODO-14-coq-commands`), or when |Coq| has been compiled with a +version of OCaml that supports native Dynlink (≥ 3.11). + + +Variants: + + +.. 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. + + + +Error messages: + +.. exn:: File not found on loadpath : @string + +.. exn:: Loading of ML object file forbidden in a native |Coq| + + + +.. cmd:: Print ML Modules. + +This prints the name of all OCaml modules loaded with ``Declare +ML Module``. To know from where these module were loaded, the user +should use the command Locate File (see Section :ref:`TODO-6.6.10-locate-file`) + + +.. _loadpath: + +Loadpath +------------ + +Loadpaths are preferably managed using |Coq| command line options (see +Section `2.6.3-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 :n:`@string` which +can be any valid path. + + +Variants: + + +.. cmdv:: Cd. + +Is equivalent to Pwd. + + + +.. cmd:: Add LoadPath @string as @dirpath. + +This command is equivalent to the command line option +``-Q`` :n:`@string` :n:`@dirpath`. It adds the physical directory string to the current +|Coq| loadpath and maps it to the logical directory dirpath. + +Variants: + + +.. cmdv:: Add LoadPath @string. + +Performs as Add LoadPath :n:`@string` as :n:`@dirpath` but +for the empty directory path. + + + +.. cmd:: Add Rec LoadPath @string as @dirpath. + +This command is equivalent to the command line option +``-R`` :n:`@string` :n:`@dirpath`. It adds the physical directory string and all its +subdirectories to the current |Coq| loadpath. + +Variants: + + +.. cmdv:: Add Rec LoadPath @string. + +Works as ``Add Rec LoadPath`` :n:`@string` as :n:`@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. + + +Variants: + + +.. cmdv:: Print LoadPath @dirpath. + +Works as ``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:`TODO-6.5-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 ``Declare ML Module`` +in Section :ref:`TODO-6.5-compiled-files`). + + +.. 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:`TODO-6.5-compiled-files`). + + +.. 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. + + +Error messages: + +.. exn:: @ident: no such entry + +Variants: + +.. cmd:: Reset Initial. + +Goes back to the initial state, just after the start +of the interactive session. + + + +.. cmd:: Back. + +This commands undoes all the effects of the last vernacular command. +Commands read from a vernacular file via a ``Load`` are considered as a +single command. Proof management commands are also handled by this +command (see Chapter :ref:`TODO-7-proof-handling`). 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 +``Qed``, the management information about the closed proof has been +discarded. In this case, ``Back`` will then undo all the proof steps up to +the statement of this proof. + + +Variants: + + +.. cmdv:: Back @num. + +Undoes :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. + + + +Error messages: + + +.. 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 ``Back`` (see +above), the ``BackTo`` command now handles proof states. For that, it may +have to undo some extra commands and end on a state `num′ ≤ num` if +necessary. + + +Variants: + + +.. cmdv:: Backtrack @num @num @num. + +`Backtrack` is a *deprecated* form of +`BackTo` which allows explicitly manipulating the proof environment. The +three numbers represent the following: + + + *first number* : State label to reach, as for BackTo. + + *second number* : *Proof state number* to unbury once aborts have been done. + |Coq| will compute the number of Undo to perform (see Chapter :ref:`TODO-7-proof-handling`). + + *third number* : Number of Abort to perform, i.e. the number of currently + opened nested proofs that must be canceled (see Chapter :ref:`TODO-7-proof-handling`). + + + + +Error messages: + + +.. 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 implementors 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();; + + + +Warnings: + + +#. It only works with the bytecode version of |Coq| (i.e. `coqtop.byte`, + see Section `TODO-14.1-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 `14.3.2-customization-by-envionment-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. + + +.. cmd:: Set Default Timeout @num. + +After using this command, all subsequent commands behave as if they +were passed to a Timeout command. Commands already starting by a +`Timeout` are unaffected. + + +.. cmd:: Unset Default Timeout. + +This command turns off the use of a default timeout. + +.. cmd:: Test Default Timeout. + +This command displays whether some default timeout has been set or not. + +.. 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. + +Error messages: + +.. exn:: The command has not failed! + +.. _controlling-display: + +Controlling display +----------------------- + + +.. cmd:: Set Silent. + +This command turns off the normal displaying. + + +.. cmd:: Unset Silent. + +This command turns the normal display on. + +TODO : check that spaces are handled well + +.. cmd:: Set Warnings ‘‘(@ident {* , @ident } )’’. + +This command 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`. + + +.. cmd:: Set Search Output Name Only. + +This command restricts the output of search commands to identifier +names; turning it on causes invocations of ``Search``, ``SearchHead``, +``SearchPattern``, ``SearchRewrite`` etc. to omit types from their output, +printing only identifiers. + + +.. cmd:: Unset Search Output Name Only. + +This command turns type display in search results back on. + + +.. cmd:: Set Printing Width @integer. + +This command sets which left-aligned part of the width of the screen +is used for display. + + +.. cmd:: Unset Printing Width. + +This command resets the width of the screen used for display to its +default value (which is 78 at the time of writing this documentation). + + +.. cmd:: Test Printing Width. + +This command displays the current screen width used for display. + + +.. cmd:: Set Printing Depth @integer. + +This command sets the nesting depth of the formatter used for pretty- +printing. Beyond this depth, display of subterms is replaced by dots. + + +.. cmd:: Unset Printing Depth. + +This command resets the nesting depth of the formatter used for +pretty-printing to its default value (at the time of writing this +documentation, the default value is 50). + + +.. cmd:: Test Printing Depth. + +This command displays the current nesting depth used for display. + + +.. cmd:: Unset Printing Compact Contexts. + +This command resets the displaying of goals contexts to non compact +mode (default at the time of writing this documentation). Non compact +means that consecutive variables of different types are printed on +different lines. + + +.. cmd:: Set Printing Compact Contexts. + +This command sets the displaying of goals contexts to compact mode. +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 Set Printing +Width above). + + +.. cmd:: Test Printing Compact Contexts. + +This command displays the current state of compaction of goal. + + +.. cmd:: Unset Printing Unfocused. + +This command resets the displaying of goals to focused goals only +(default). Unfocused goals are created by focusing other goals with +bullets (see :ref:`TODO-7.2.7-bullets`) or curly braces (see `7.2.6-curly-braces`). + + +.. cmd:: Set Printing Unfocused. + +This command enables the displaying of unfocused goals. The goals are +displayed after the focused ones and are distinguished by a separator. + + +.. cmd:: Test Printing Unfocused. + +This command displays the current state of unfocused goals display. + + +.. cmd:: Set Printing Dependent Evars Line. + +This command enables the printing of the “(dependent evars: …)” line +when -emacs is passed. + + +.. cmd:: Unset Printing Dependent Evars Line. + +This command disables the printing of the “(dependent evars: …)” line +when -emacs is passed. + + +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 [`98`]. 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 ``Definition`` or ``Let`` (with an explicit body), or by a command +assimilated to a definition such as ``Fixpoint``, ``Program Definition``, etc, +or by a proof ended by ``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). + +``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:`TODO-4.3-conversion-rules`) of two distinct +applied constants. + +The scope of ``Opaque`` is limited to the current section, or current +file, unless the variant ``Global Opaque`` is used. + + +See also: sections :ref:`TODO-8.7-performing-computations`, :ref:`TODO-8.16-automatizing`, :ref:`TODO-7.1-switching-on-off-proof-editing-mode` + + +Error messages: + + +.. 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 ``Opaque`` `foo` `bar` and if `bar` does not exist, `foo` is set opaque. + +.. cmd:: Transparent {+ @qualid }. + +This command is the converse of `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. + +The scope of Transparent is limited to the current section, or current +file, unless the variant ``Global Transparent`` is +used. + + +Error messages: + + +.. exn:: The reference @qualid was not found in the current environment + +There is no constant referred by :n:`@qualid` in the environment. + + + +See also: sections :ref:`TODO-8.7-performing-computations`, :ref:`TODO-8.16-automatizing`, :ref:`TODO-7.1-switching-on-off-proof-editing-mode` + + +.. 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 −∞) + + +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 ``Transparent`` and +``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. + + +Error messages: + + +.. exn:: The reference is not unfoldable. + + + +Variants: + + +.. 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 ``Eval`` :n:`@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 +``Ltac`` `ident` ``:=`` `convtactic`. + + +See also: sections :ref:`TODO-8.7-performing-computations` + + +.. _controlling-locality-of-commands: + +Controlling the locality of commands +----------------------------------------- + + +.. cmd:: Local @command. +.. cmd:: 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 ``Coercion`` + (see Section :ref:`TODO-2.8-coercions`) and ``Strategy`` (see Section :ref:`TODO-6.10.3-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 extent 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 ``Implicit Arguments`` (see + Section :ref:`TODO-2.7-implicit-arguments`), Ltac (see Chapter :ref:`TODO-9-tactic-language`) or ``Notation`` (see Section + :ref:`TODO-12.1-notations`) 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 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 + occurs in. The ``Transparent`` and ``Opaque`` (see Section :ref:`TODO-6.10-opaque`) 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 ``Set`` and ``Unset`` commands belong to this + category. |