NOTE TO USERS
On October 30, 2015, I pushed changes to the configuration system, specifically the variable grass-grass-programs-alist. The new system is simpler to set up, but incompatible with the previous system. If you have customized this variable, you should erase your old customization and redo it according the the info below.
grass-mode is actually two closely related modes. igrass-mode handles the grass program itself, and is a variant of Emacs' standard shell-mode. If you use M-x shell you'll be right at home. sgrass-mode is for editing grass script files, and allows you to pass code directly from the script to the process in the igrass buffer.
grass-mode is available from the Melpa repository. If you haven't used Melpa before you need to set it up in your .emacs:
(require 'package) (add-to-list 'package-archives '("melpa" . "http://melpa.milkbox.net/packages/") t)
This works for Emacs 24. There are additional steps if you're using Emacs 23 -- see the Melpa site for details. Emacs 22 and lower may not work with Elpa, and are untested with grass-mode.
Alternatively, you can install grass-mode manually, but note that it depends on the dash library: this needs to be installed before you install grass-mode. after that, you need to save the file grass-mode.el to a convenient directory and tell Emacs where it is. Then require grass-mode. Assuming you've saved the file to "/.emacs.d/grass-mode/grass-mode.el", the following two lines in your .emacs will do it:
(add-to-list 'load-path "~/.emacs.d/grass-mode") (require 'grass-mode)
You may also need to configure a few variables. These are accessible through Emacs' customization facility. To access the grass page, use M-x customize-group grass-mode. The default values are based on locations in a standard Debian GNU/Linux installation.
GRASS programs alist
The most important option is the GRASS programs alist. In the customize interface, you add the correct values to each slot, which is relatively straightforward to do. If you wish to set this in elisp, the value is a list of lists. Each sublist has four parts:
- Program name: this is a string, used to refer to the particular GRASS program. It can be anything you like, such as "Grass64", "7.0", "grass".
- GRASS executable: this is the path to the grass program. By default it is set to /usr/bin/grass, which should work for Debian and probably Ubuntu. If it doesn't you'll need to find where the grass program is stored on your installation.
NB for Mac users - if you installed GRASS from the official framework, you need to use grass.sh here, which is usually found at /Applications/GRASS-X.Y.app/Contents/MacOS where X.Y is the version of GRASS installed. If you installed GRASS via homebrew, simply pointing to the grassXY executable which is found in /usr/local/bin/ should work.
- Installation directory: this is the path to the directory where all the GRASS scripts and help files are found (in the subdirectories 'bin', 'scripts', and 'docs/html'). The default is /usr/lib/grass70, again following Debian conventions.
If you aren't sure of the installation directory, GRASS can tell you. Issue the following command at a command prompt:
grass --config path
C:\>grass70.bat --config path
If there is only one list in GRASS programs alist, then whenever you start grass these are the options that will be used. If there is more than one list, each time you start GRASS you will be asked which version you want to run. This allows you to run multiple grass installations, such as GRASS 6.4, GRASS 7.0 etc, all from the same Emacs instance. At present, you cannot run them concurrently, but that feature will be added in future.
Translating from the customization system to raw elisp can be confusing. If you want to set this variable in your .emacs, use the following syntax:
(customize-set-variable 'grass-grass-programs-alist '(("71" "/usr/local/bin/grass71" "/usr/local/grass-7.1") ("Grass70" "/usr/bin/grass" "/usr/lib/grass70")))
- GRASS completion file - grass-mode generates completion tables for each version of grass you use. This is a slow process, so to save time the tables are stored in the file specified by this variable. By default, it will be in your /.emacs.d/ directory. This should work across platforms, but you can change it if you like. If you change it after the completions are generated, you should move the original file to the new location, or you will have to regenerate the completions next time you start grass.
- GRASS Log dir - by default, grass-mode will store a text log of your interactive session in this directory. You can tell it to use a different location, or turn off logging by setting this to nil.
- Grass Help Browser - which web browser to use when reading the help docs. At present two options are available, selected by setting the value of this variable to one of the following symbols (not strings!): external, for the external browser called via browse-url; or eww, to call Emacs brand new (as of 24.4) elisp web browser, eww (the default).
- GRASS Prompt and GRASS Prompt 2 are the Bash-style prompt strings used by GRASS.
- grassdata is the directory that contains your GRASS locations. Default: "/grassdata"
- GRASS Default Location and Mapset - for convenience during startup.
- GRASS Completion Lookup Table: These is where all the completion targets are stored between sessions. You shouldn't edit it directly. Instead, you can clear the completions for a particular grass program with grass-flush-completions, or regenerate them with grass-redo-completions. Under normal circumstances, you should only need to redo completions when you install a new version of GRASS. Otherwise, the values are stored between sessions.
Starting a session
You can start a new grass session with `M-x grass`. If you have more than one grass version installed, you will be asked which one you wish to run (see GRASS programs alist above).
Next you will be prompted for a location, then a mapset. You may set default values in the customization group (see above). GRASS will have already scanned your grassdata directory, so it knows what locations you have, and will offer tab-completion for them. Once the location is selected, it will scan the mapsets for that location, so you can again use tab completion to select your mapset.
If you want to create a new location, enter the name of the new location instead of an existing one at this point. You will then be prompted for the filename of a georeferenced file to use to set the projection of your new location.
If this is the first time you have run this grass version from within Emacs, you will be asked if you'd like to generate tab-completions. If you answer yes, grass-mode will read in the command parameter and possible values for each script (i.e., d.vect, v.in.ogr etc), and build a lookup table with them. This takes several minutes, but the results are saved so it doesn't need to happen again for this grass version.
If you decline to generate tab completions, you can still run grass, but the tab-completions provided at the prompt will be limited to script names and bash commands.
GRASS should now start in the selected location and mapset. You are now in 'igrass-mode', which serves as a front-end to the grass inferior process. This mode is derived from shell-mode, so if you use M-x shell, all of your favourite commands should be available, and tab-completion now includes all of your GRASS programs and scripts. Some of the key features are:
- M-p and M-n cycle to the previous and next item in the command-line history, respectively. (comint-previous-input and comint-next-input)
- M-r invokes Regexp-history interactive search, which allows you to use regular expressions to search through your command history.
- Moving the cursor to a previous command line and pressing ENTER will send that line to GRASS to be run again. C-ENTER copies the command to the next prompt so you can edit it before running it.
- C-c C-p moves the cursor back to the previous input, sort of, but it's buggy (my fault, I don't know why). C-c C-o normally clears the last output, but it looks like I may have broken that completely in igrass-mode.
These are the commands I use most often in shell-mode, but careful study will doubtless reveal more that you may find useful.
Reading the Fine Manual
Both igrass-mode and sgrass-mode know where the html help files are, and you can browse them with C-c C-v. Depending on your configuration, you will see the files displayed eww in an Emacs window, or the files will pop up in your default browser. Tab completion works for command names here, so, for instance, r.<TAB> will give you a list of all the raster help files.
w3m was the most convenient help browser when I wrote this mode. However, Emacs now ships with its own built-in browser called eww. eww is now the default help viewer for grass-mode, and w3m is no longer supported.
You can read the manual by entering `C-c C-v` (same as in ESS, if you use that mode). You will then be prompted for a grass command. Hit enter, and the help page opens, either in eww or in your external browser.
If you are using an external browser, you are on your own. If you are using eww, you have more features available. The GRASS-specific features are packaged into the ghj-minor-mode (an acronym for grass-help-jump-minor-mode). The provides three new commands, in addition to what eww has out of the box.
ghj-jump-to-help-index, bound to the j key. Pressing j, followed by one of the following letters, will open the indicated manual page
- h: The main index
- v: The vector index
- r: The raster index
- d: The display index
- b: The database index
- g: The general index
- Any other key will jump to the main index
grass-view-help, bound to h and also C-c C-v key. Prompts you for a GRASS command and jumps to the help page for that command.
ghj-link-menu, bound to m, prompts you for one of the links on the current page.
Command line completion
Tab-completion now mostly does what you'd expect. TAB at the command prompt will complete to anything available in your shell, including GRASS programs (d.vect etc.), filenames, or other programs visible to the shell (ls, rm etc.)
Once you have entered a complete command name at the prompt, further TAB-ing will complete the parameter names for your. For example, once you've entered
TAB completion will offer you map, type, color etc.
For parameters with a set list of possible values, such as d.vect icon=, you will be offered value completion as well. Many parameters that take a file name as a value will also work. For example:
tab will offer you a list of vector maps. Raster maps and types are also supported.
If you enable /eldoc-mode/, you will be treated to helpful documentation in the minibuffer while you work. By default, the label or description of each command, parameter and flag will be displayed. If you would prefer to see the parameters for the commands listed, instead of the description of the command, you need to set the user option grass-eldoc-args to a non-nil value. You can do this through the grass-mode customization group.
To turn on eldoc-mode automatically in igrass-mode, add the following to your .emacs:
(defun my-grass-mode-hook (eldoc-mode)) (add-hook 'igrass-mode-hook 'my-grass-mode-hook)
You can change locations with C-c C-l. Just follow the prompts. This is the recommended way to switch locations; invoking g.mapset directly will not update your GRASS prompt, and grass-mode will offer you the wrong maps for tab completion.
sgrass minor mode
This is the mode for editing GRASS script files. At present, it doesn't know when you want to use it, so you have to call it specifically after opening a script file: `M-x sgrass`.
Once you've enabled `sgrass`, you have access to the same parameter completion and map-lookup features as igrass, using the key-combination M-tab. You also get GRASS-aware syntax highlighting.
You can interact with the GRASS process. Currently, it's pretty basic: C-c C-r will pass the active region, C-c C-n will pass the current line. You also have access to the help (C-c C-v), and can change the location with C-c C-l. Note that the location and mapset are shared between igrass and sgrass mode - you can't yet use different grass processes at the same time.