Bitbucket is a code hosting site with unlimited public and private repositories. We're also free for small teams!

Close

Introduction to sage-mode

Installation and setup

There are three possibilities for installing sage-mode:

Option 1. Use the sage-mode bundled with Sage

This is the easiest. Since the spkg is already installed, you only need to activate it in Sage and in Emacs. For the former, run

sage -f sage_mode

For the latter, then somewhere in your .emacs add the following

(add-to-list 'load-path "$INSTALL_DIR")
(require 'sage "sage")
(setq sage-command "$SAGE_ROOT/sage")

where $INSTALL_DIR and $SAGE_ROOT have been replaced with the respective paths on you machine. $INSTALL_DIR refers to the directory of the sage-mode Emacs files: these are usually located in

  $SAGE_ROOT/local/share/emacs

Furthermore, if you would like typesetting of Sage results, consider customizing sage-view-default-commands and adding the following lines to your .emacs (after requiring sage):

(add-hook 'sage-startup-after-prompt-hook 'sage-view)

Also consider running (customize-group 'sage) in Emacs to see more options.

Option 2. Download a pre-compiled spkg at the sage-mode Bitbucket repository

Once you have downloaded the spkg for the version you want, you install the spkg in Sage by running

sage -f sage_mode_<version>.spkg

where sage_mode_<version>.spkg refers to the file you have downloaded.

You can then follow the remaining steps of Option 1 to install sage-mode in Emacs.

Option 3. Download the newest code from the Bitbucket repository.

The most cutting edge solution is to clone the Bitbucket repository: first, make sure you have an installation of Mercurial. Then in an appropriate directory, run

 hg clone https://bitbucket.org/gvol/sage-mode

Then you can either create and install an spkg, or simply point Emacs at the directory, by adding something like the following to your .emacs:

(add-to-list 'load-path "/path/to/sage-mode/emacs/")
(require 'sage "sage")

To create an spkg, go to the sage-mode folder that you checked out, and run

 ./make-spkg.sh $VERSION

where instead of $VERSION, you write a version number. The version "number" can be anything. It might be useful for later reference to use as $VERSION something which can identify the exaxt version you built, such as the hash of the latest commit (found with hg id -i -r .).

In any case, this creates a file sage_mode_<version>.spkg. You can then follow the steps in Option 2 as if you had downloaded this spkg from the repository.

The inferior sage shell

The primary element of sage-mode is interaction with a Sage shell in a buffer. Run the function sage in Emacs to start it. The new buffer communicates directly with a Sage shell in the background and behaves very much like it. You just type and send the command with <Enter>:

sage: 2+2
4
sage: x^2 + 1
x^2 + 1

If you activated sage-view in the setup, the last output line should be properly typeset with LaTeX. This already then beats running the Sage shell in a usual terminal; however, we are just getting started.

The shell also behaves like an Emacs shell:

  • Pressing M-p or C-up goes through earlier input.
  • The history of the shell is earlier in the buffer, and you can move around just as in any Emacs buffer. When you're not at the bottom command line, the text you enter won't send anything to the shell.
  • Pressing <Enter> on some line earlier in the buffer runs that line at the command line and returns the pointer there.
  • Pressing C-q C-j inserts a literal newline.

Of course, you also have access to tab-completion and the usual Sage help:

  • <Tab> at the command line attempts completion of current word. It understands all Sage and Python functions currently in scope, and it also completes attributes of objects. As usual in Emacs, with multiple suggestions they are presented in another window.
  • Adding ? after a name or attribute and then <Tab> shows the documentation for it in another window. Pressing <Enter> instead of <Tab> prints the documentation in the shell.
  • Adding ?? and then <Enter> prints the preceding object's source in the shell. TODO: /jsrn: This behaves as above when I do it, but when iandrus does it, it opens the source file. Why?

You can type quit to kill the Sage shell, or you can kill the entire buffer.

Editing your Sage code

Most of your code you will want to structure properly and keep, and so will naturally be edited in separate files and not typed directly into the Sage shell. When opening a .sage-file, sage-mode will be activated, providing you with syntax highlighting and various interaction with the Sage shell.

If you already have an open Sage shell, the newly opened file should be aware of it. If not, you can open a new shell with the sage function. Now you have various functions for sending code to the shell:

  • sage-send-buffer or C-c C-c sends the entire buffer's contents to the shell.
  • sage-send-defun or C-c C-d sends the def that the pointer is currently standing in.
  • sage-send-region or C-c C-r sends the currently marked region.
  • sage-attach-this-file will attach this file to the Sage shell, so that every time you execute something in the shell, that file will be reloaded if it has changed.

There are a few more such functions; type C-h m for a summary. Note that these functions are not exactly the same as typing in the shell: in particular, the result of the last line of code is not printed.

Of course, many .sage-files can be attached to the same shell, allowing for quick editing and reloading of your various sources. There is a pitfall here, though: after modifying a function or class, it is necessary to reload all functions, classes and objects referring to it, so that the Sage shell is not using the old definition. Sometimes it is easier or even necessary to restart the Sage shell in order to achieve this.

If you later restart the Sage shell, you might need to make buffers with .sage-files aware of the new shell. This is most easily done by revisiting the file: C-x C-v <Enter>.

Custom initialisation of Sage

Perhaps you would like to have Sage initialise with custom code when run from inside Emacs. As usual, you can use $HOME/.sage/sage.init for code which should run immediately after Sage starts. To run code only when Sage is run from inside Emacs is then done simply by guarding the code based on the environment variable $EMACS:

import os
if 'EMACS' in os.environ and os.environ['EMACS']:
    <Custom initialisation code goes here>

Recent activity

Tip: Filter by directory path e.g. /media app.js to search for public/media/app.js.
Tip: Use camelCasing e.g. ProjME to search for ProjectModifiedEvent.java.
Tip: Filter by extension type e.g. /repo .js to search for all .js files in the /repo directory.
Tip: Separate your search with spaces e.g. /ssh pom.xml to search for src/ssh/pom.xml.
Tip: Use ↑ and ↓ arrow keys to navigate and return to view the file.
Tip: You can also navigate files with Ctrl+j (next) and Ctrl+k (previous) and view the file with Ctrl+o.
Tip: You can also navigate files with Alt+j (next) and Alt+k (previous) and view the file with Alt+o.