Emacs support for Stan
- 2020-08-30 Version 10.2.0 update for Stan version 2.24
Packages and tools included
stan-modeis a major mode for editing Stan files. Its current features include:
- syntax highlighting
- imenu support for blocks, variables, and user-defined functions.
indent-stan-files: A shell script that uses
stan-modeto indent a file.
stan-language-definitions: The file
stan_lang.jsoncontains all keywords, functions (with their signatures and documentation) in the Stan modeling language. This is used to generate the keyword lists and snippets used by the modes. It could also be useful for developers designing tools for Stan, e.g. other editor modes.
Example configurations are available in the package-specific README.md file under each subfolder (linked above).
The recommended way to install these packages is using the built-in package manager:
These packages are available from MELPA.
If you're not already using MELPA, follow its installation instructions.
You can then install the packages using the following commands:
M-x package-install [RET] stan-mode [RET]
M-x package-install [RET] company-stan [RET]
M-x package-install [RET] eldoc-stan [RET]
M-x package-install [RET] flycheck-stan [RET]
M-x package-install [RET] stan-snippets [RET]
If the installation does not work, try refreshing the package list:
M-x package-refresh-contents [RET]
Or add the following to your
init.el to ensure installation of these packages:
(package-refresh-contents) (mapc (lambda (p) (unless (package-installed-p p) (package-install p))) '(stan-mode company-stan eldoc-stan flycheck-stan stan-snippets))
Simply add the following to your configuration Cask file:
(source melpa) (depends-on "stan-mode") (depends-on "company-stan") (depends-on "eldoc-stan") (depends-on "flycheck-stan") (depends-on "stan-snippets")
and from the command line in the same directory as the Cask file use
cask to install the packages,
$ cask install
See the Cask documentation for more information.
The package maintainer's current development version is available on Github. This can be cloned as follows. You can also use
--recurse-submodules, but this will recurse more than one level, which is not necessary for our purpose.
# Clone the develop branch. Change as appropriate. $ git clone --branch=develop https://github.com/stan-dev/stan-mode.git $ cd stan-mode # Clone submodules $ git submodule update --init -- stan-language-definitions $ git submodule update --init -- local-melpa $ git submodule update --init -- rstanarm # To run automated tests, do the following. make clean; make all # If just installing, do the following. make local-melpa
Add the following to your
init.el. The local development versions will be installed provided their version numbers are greater than the ones in MELPA.
;; To make the local package archive visible. (let ((local-melpa-stan "your-path/stan-mode/local-melpa/packages")) (when (file-exists-p local-melpa-stan) (add-to-list 'package-archives `("local-melpa-stan" . ,local-melpa-stan) t))) ;; Installation (package-refresh-contents) (mapc (lambda (p) (unless (package-installed-p p) (package-install p))) '(stan-mode company-stan eldoc-stan flycheck-stan stan-snippets ;; If you use auto-complete, uncomment the line below. ;; ac-stan ))
The recommended mode of configuration is via the
use-package. One example of configuration is included below. Please the package-specific README files for configuration without use-package.
;; Uncomment the line below if not required elsewhere. ;; (require 'use-package) ;;; stan-mode.el (use-package stan-mode :mode ("\\.stan\\'" . stan-mode) :hook (stan-mode . stan-mode-setup) ;; :config ;; The officially recommended offset is 2. (setq stan-indentation-offset 2)) ;;; company-stan.el (use-package company-stan :hook (stan-mode . company-stan-setup) ;; :config ;; Whether to use fuzzy matching in `company-stan' (setq company-stan-fuzzy nil)) ;;; eldoc-stan.el (use-package eldoc-stan :hook (stan-mode . eldoc-stan-setup) ;; :config ;; No configuration options as of now. ) ;;; flycheck-stan.el (use-package flycheck-stan ;; Add a hook to setup `flycheck-stan' upon `stan-mode' entry :hook ((stan-mode . flycheck-stan-stanc2-setup) (stan-mode . flycheck-stan-stanc3-setup)) :config ;; A string containing the name or the path of the stanc2 executable ;; If nil, defaults to `stanc2' (setq flycheck-stanc-executable nil) ;; A string containing the name or the path of the stanc2 executable ;; If nil, defaults to `stanc3' (setq flycheck-stanc3-executable nil)) ;;; stan-snippets.el (use-package stan-snippets :hook (stan-mode . stan-snippets-initialize) ;; :config ;; No configuration options as of now. ) ;;; ac-stan.el (Not on MELPA; Need manual installation) (use-package ac-stan :load-path "path-to-your-directory/ac-stan/" ;; Delete the line below if using. :disabled t :hook (stan-mode . stan-ac-mode-setup) ;; :config ;; No configuration options as of now. )
Updating packages for a new Stan version
To update stan-mode when a new version of the Stan language comes out:
stan-lang/stan-functions-MAJORVERSION_MINORVERSION.txtwith the newest version generated by
extract_function_sigs.pyin the stan-dev/docs repo. The version string must exist in the file name and it is the Stan version.
- Clean and rebuild all generated files. Fix issues in testing and linting as necessary.
$ make clean $ make all
- Save and commit the changes.
- Bump the version number of the emacs packages. For example, to bump to 10.0.0. This is the emacs stan-mode package version, which is different than the Stan language version.
$ ./update-versions.sh 10.0.0
- If the changes are minor, tag the commit and push the tag for MELPA Stable. If making major changes, it is better to create a pull request on Github to document and discuss.
$ git tag v10.0.0 $ git push --tags
Emacs lisp good practices
The packages must meet the MELPA standards. See "Making your package ready for inclusion". The packages ensure these standards through the following automated examinations, which are mandated in
For testing only, use
make test at the top-level or in a subfolder. For linting only, use
make lint at the top-level (both types) or
make lint-package and
make lint-elisp in a subfolder.
Available top-level make commands
The following make commands are available at the top-level
Makefile. Each package has its own
Makefile and common included file
common.mk, allowing us to work on them individually.
||Build data files for each package.|
||Create a local archive
||Run both linting for each package.|
||Show elisp files designated for byte-compilation for each package.|
||Move snippet files under
stan-language-definitions: Provides language definitions. All packages depend on this for definitions.
local-melpa: Provides a local version of MELPA to make the current development version available via the
package.elinterface. Used to avoid installability issue during linting. Also allows package installation checking.
rstanarm: Used to provide examples of complicated stan code in indentation and syntax highlighting tests for the
- eldoc-stan: Correctly ignore , in [,]
- flycheck-stan: Handle end of column
- company-stan: Detect context and modify candidates
All packages are free software under the GPL v3.