https://github.com/cpitclaudel/company-coq
A Coq IDE build on top of Proof General's Coq mode
https://github.com/cpitclaudel/company-coq
company-mode coq emacs integrated-development-environment proof-assistant proof-general
Last synced: 19 days ago
JSON representation
A Coq IDE build on top of Proof General's Coq mode
- Host: GitHub
- URL: https://github.com/cpitclaudel/company-coq
- Owner: cpitclaudel
- License: gpl-3.0
- Created: 2015-02-15T17:37:32.000Z (about 10 years ago)
- Default Branch: master
- Last Pushed: 2023-02-03T02:53:53.000Z (about 2 years ago)
- Last Synced: 2025-03-30T00:07:29.068Z (26 days ago)
- Topics: company-mode, coq, emacs, integrated-development-environment, proof-assistant, proof-general
- Language: Emacs Lisp
- Homepage:
- Size: 22.8 MB
- Stars: 356
- Watchers: 9
- Forks: 28
- Open Issues: 100
-
Metadata Files:
- Readme: README.md
- License: COPYING
Awesome Lists containing this project
- awesome-coq - Company-Coq - IDE extensions for Proof General's Coq mode. (Projects / User Interfaces)
- awesome-coq - Company-Coq - IDE extensions for Proof General's Coq mode. (Projects / User Interfaces)
README
# Company-coq
[](COPYING)
[](http://melpa.org/#/company-coq)
[](http://dx.doi.org/10.5281/zenodo.44331)
A collection of extensions for Proof General's Coq mode.
See [screenshots](#screenshots) below, or jump right to [setup instructions](#setup) and try the tutorial with M-x company-coq-tutorial after setting up!
## Setup
### MELPA
Both `proof-general` and `company-coq` are on [MELPA](https://melpa.org/#/getting-started), a repository of Emacs packages. Skip this step if you already use MELPA. Otherwise, add the following to your `.emacs` and restart Emacs:
```elisp
(require 'package)
(add-to-list 'package-archives '("melpa" . "https://melpa.org/packages/") t)
(package-initialize)
```
### Proof General and Company-Coq
Install and byte-compile Proof General, Company-Coq, and its
dependencies by typing successively:
* M-x package-refresh-contents RET
* M-x package-install RET proof-general RET
* M-x package-install RET company-coq RET
(some dependencies will produce a few warnings; that's OK).
To enable company-coq automatically, add the following to your `.emacs`:
```elisp
;; Load company-coq when opening Coq files
(add-hook 'coq-mode-hook #'company-coq-mode)
```
Then restart and launch the tutorial with M-x company-coq-tutorial!
## Screenshots
#### Prettification of operators, types, and subscripts
#### Auto-completion
#### Snippets and smart commands
#### Outlines, code folding, and jumping to definition
#### Help with errors
#### Misc. extensions of Proof General
## Citing
Use `M-x company-coq-cite` to insert the BibTeX entries for Coq, Proof General, and `company-coq` in the current buffer.
```latex
@InProceedings{CompanyCoq2016,
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},
Url = {http://hdl.handle.net/1721.1/101149}
}
```
## Quick start guide
**You can check out the interactive tutorial by pressing M-x company-coq-tutorial RET.** See also the **[screenshots](#screenshots)** above!
`company-coq` should be pretty transparent. Completion windows will pop up when `company-coq` has suggestions to make. By default, this would be when you start writing a tactic name or a command. You can also launch manual completion by using C-RET (or whatever was originally assigned to `proof-script-complete` in Coq mode).
Once auto-completion has started, the following key bindings are available:
* RET selects a completion
* C-g interrupts completion.
* C-h and <f1> display documentation for the currently highlighted keyword, identifier, or tactic.
* C-M-v scrolls down in the documentation window.
* C-w opens source view when available (alternatively, pressing M-. browses to the definition of the identifier at point).
Selecting a completion often inserts a snippet with holes at the current point (`company-coq` uses `yasnippet` as the snippet backend). You can move between holes by using <tab> and S-<tab>.
Loading `company-coq` also binds the following keys:
* M-RET inserts a new `match` case (`| _ => _`).
* M-S-RET inserts a new `match goal` rule (`| [ H: _ |- _ ] => _`).
* C-c C-a C-x extracts the current goal into a separate lemma.
* C-down-mouse-1 (i.e. C-click) shows an inline quick help box for the identifier under point. The box disappears when the mouse is released. Pressing the <menu> key or M-F12 also works.
* M-. jumps to the source of the identifier at point, when available.
* C-c C-d opens the documentation of the identifier at point (for theorems and definitions; for tactics, use C-h during completion).
* C-c C-, opens an outline of the code in a separate buffer (using `occur`).
* C-c C-/ folds the current definition, or all definitions in the file if repeated.
* C-c C-\\ unfolds the current definition, or all definitions in the file if repeated.
* S-TAB folds or unfolds the current bullet or curly-brace-delimited block. With C-u, S-TAB folds all bullets and braces in the current buffer.
* C-c C-& looks up (grep) the current word in files in the current directory's subtree.
* C-c C-a C-e tries to match the last output to a documented error message, and displays the relevant section of the manual if it finds one.
* C-c C-a C-d parses the last unification error, and shows a diff of the two types that can't unify. If there is no such error, C-c C-a C-d shows a diff comparing the last goal to the previous one.
## Tips
* Most completion engines support fuzzy matching: you can type `Require Import C.N..Ab.ZPa` and press RET to insert `Coq.Numbers.Integer.Abstract.ZParity`, and typing `setrewin` is enough to insert setoid_rewrite term in ident. You can (and must) omit spaces: `SLD` will insert `Set Ltac Debug` (of course `SetLtDeb` will also work), and `ULD` will insert `Unset Ltac Debug`.
* Using M-S-RET to insert new cases in a `match goal` saves a lot of time (and finger contortions). For the match itself, use `mgw` (for `match goal with`).
* The point-and-click feature (quick help) also works in non-graphic mode, if you enable `xterm-mouse-mode`.
* `company-coq` improves on some of Proof General's features. Try C-c C-a RET nat RET.
* Try right-clicking on a [Require Import] statement.
* Use `a__b` to display `a``b`.
`company-coq` is implemented as a collection of small modules implementing independent features; check out `M-x customize-variable RET company-coq-disabled-features RET` and `M-x customize-group RET company-coq RET` for more info!
## Troubleshooting
### Empty squares in place of math operators, or incorrect line spacing
If you see blank squares appear where there should be math symbols (`forall`, `exists`, etc.), or if some lines suddenly become very tall, you may be missing a proper math font. See [Installing a math font](#installing-a-math-font), or insert the following snippet in your `.emacs` to disable symbols beautification:
```elisp
;; Disable symbol prettification
(setq company-coq-disabled-features '(prettify-symbols))
```
On the other hand, if you like the prettification feature a lot, you can enable it in the terminal:
``` elisp
(setq company-coq-features/prettify-symbols-in-terminals t)
```
Technical note: Proof General [also offers](http://proofgeneral.inf.ed.ac.uk/htmlshow.php?title=Proof+General+user+manual+%28latest+release%29&file=releases%2FProofGeneral-latest%2Fdoc%2FProofGeneral%2FProofGeneral_5.html#Unicode-Tokens-mode) a Unicode keywords facility. `company-coq`'s implementation is based on the `prettify-symbols-mode` facility found in Emacs 24.4+, yielding a more compact (and faster?) implementation.
## Advanced topics
### Installing a math font
For prettification to work properly, you'll need a font with proper symbol support. [Symbola](https://fonts2u.com/symbola.font) (up to version 10.23), FreeMono, XITS Math, Segoe UI Symbol, Latin Modern, and Cambria Math will all work. If Emacs doesn't fallback properly, you can use the following snippet (change `XITS Math` and `DejaVu sans Mono` to the Unicode font you just downloaded and to your usual monospace font, respectively):
```elisp
(set-fontset-font t 'unicode (font-spec :name "XITS Math") nil 'prepend)
(set-fontset-font t 'greek (font-spec :name "DejaVu sans Mono") nil 'prepend)
```
Or, in Emacs < 25:
```elisp
(dolist (ft (fontset-list))
(set-fontset-font ft 'unicode (font-spec :name "YOUR-USUAL-FONT"))
(set-fontset-font ft 'unicode (font-spec :name "XITS Math") nil 'append))
```
#### Fixing math indentation
Using a variable-width font for symbols will break indentation. See [this other project of mine](https://github.com/cpitclaudel/monospacifier#pre-monospacified-fonts-monospace-fonts-with-good-unicode-coverage) to download a monospace-friendly symbols font. You'll want to replace the snippet above by following (adjusting `Latin Modern Math` and `DejaVu sans Mono` as appropriate):
```elisp
(set-fontset-font t 'unicode (font-spec :name "Latin Modern Math Monospacified for DejaVu sans Mono") nil 'prepend)
```
Or, in Emacs < 25:
```elisp
(dolist (ft (fontset-list))
(set-fontset-font ft 'unicode (font-spec :name "YOUR-USUAL-FONT"))
(set-fontset-font ft 'unicode (font-spec :name "Latin Modern Math Monospacified for YOUR-USUAL-FONT") nil 'append))
```
### Folding all goals when a file is opened
Adding the following header to a Coq file will make company-coq hide the bodies of all bullets when the file is opened. You can also customize the `company-coq-initial-state` variable to apply the setting globally.
```coq
(* -*- company-coq-initial-fold-state: bullets; -*- *)
```
### Showing alerts for long-running proofs
If possible, `company-coq` will use the [`alert`](https://github.com/jwiegley/alert) library to display notifications when long-running proofs complete. `alert` is only needed on Windows and OSX; on Linux systems with DBus this should work out of the box. You can try it out by running the snippet below and opening another application while the proof runs; after 10 seconds company-coq will show a notification.
``` coq
Goal True.
Fail timeout 10 repeat pose 1.
```
### Registering your own symbols and math operators
#### For a single file
Add the following header to a Coq file, save, and run `M-x revert-buffer` to prettify squiggly arrows.
```coq
(* -*- company-coq-local-symbols: (("<~>" . ?↭) ("~>" . ?↝) ("<~" . ?↜)); -*- *)
```
Alternatively, you can use a special comment at the end of the file:
```coq
(* Local Variables: *)
(* company-coq-local-symbols: (("<~>" . ?↭) ("~>" . ?↝) ("<~" . ?↜)) *)
(* End: *)
```
Tip: you can use `M-x add-file-local-variable` to add this sort of variables.
#### For a single project
Create a `.dir-locals.el` file at the root of your project, and add following contents to it:
```elisp
;;; Directory Local Variables
;;; For more information see (info "(emacs) Directory Variables")
((coq-mode
(company-coq-dir-local-symbols
(("<~>" . ?↭) ("~>" . ?↝) ("<~" . ?↜)))))
```
Tip: you can use `M-x add-dir-local-variable` to add this sort of variables.
#### For all Coq files
Adjust and use the following snippet to register your own prettifications for all Coq files. This must run before `(company-coq-mode)`, so it must be added after the `company-coq` setup code above.
```elisp
(add-hook 'coq-mode-hook
(lambda ()
(setq-local prettify-symbols-alist
'((":=" . ?≜) ("Proof." . ?∵) ("Qed." . ?■)
("Defined." . ?□) ("Time" . ?⏱) ("Admitted." . ?😱)))))
```
Greek symbols can be obtained using the following mappings:
```elisp
'(("Alpha" . ?Α) ("Beta" . ?Β) ("Gamma" . ?Γ)
("Delta" . ?Δ) ("Epsilon" . ?Ε) ("Zeta" . ?Ζ)
("Eta" . ?Η) ("Theta" . ?Θ) ("Iota" . ?Ι)
("Kappa" . ?Κ) ("Lambda" . ?Λ) ("Mu" . ?Μ)
("Nu" . ?Ν) ("Xi" . ?Ξ) ("Omicron" . ?Ο)
("Pi" . ?Π) ("Rho" . ?Ρ) ("Sigma" . ?Σ)
("Tau" . ?Τ) ("Upsilon" . ?Υ) ("Phi" . ?Φ)
("Chi" . ?Χ) ("Psi" . ?Ψ) ("Omega" . ?Ω)
("alpha" . ?α) ("beta" . ?β) ("gamma" . ?γ)
("delta" . ?δ) ("epsilon" . ?ε) ("zeta" . ?ζ)
("eta" . ?η) ("theta" . ?θ) ("iota" . ?ι)
("kappa" . ?κ) ("lambda" . ?λ) ("mu" . ?μ)
("nu" . ?ν) ("xi" . ?ξ) ("omicron" . ?ο)
("pi" . ?π) ("rho" . ?ρ) ("sigma" . ?σ)
("tau" . ?τ) ("upsilon" . ?υ) ("phi" . ?φ)
("chi" . ?χ) ("psi" . ?ψ) ("omega" . ?ω))
```
in which case you may want to use a custom font for Greek characters:
```
(dolist (ft (fontset-list))
(set-fontset-font ft 'greek (font-spec :name "DejaVu Sans Mono")))
```
Tip: to add multi-character substitutions, you may want to consult [issue #201](https://github.com/cpitclaudel/company-coq/issues/201).
### Autocompleting symbols and tactics defined externally
The procedure above will give you auto-completion and documentation for tactics, commands, and theorems that you define locally, but not for theorem names and symbols defined in the libraries you load. To get the latter, add the following to your `.emacs`, before `(company-coq-mode)`:
```elisp
(setq company-coq-live-on-the-edge t)
```
### Installing from source
Use Cask.
### Special thanks
Many thanks to Pierre Courtieu for his work on Proof General, and to Jonathan Leivent and Jason Gross for their tireless bug reports and suggestions!