New feature (r16445): Browse parent/base classes from pod view; press [B] or [P]
Check the known issues before reporting.
bioperl-mode is a custom package for the Emacs editor that allows convenient BioPerl pod browsing and code template insertion.
maj -at- fortinbras -dot- us
What is it?
bioperl-mode is an Emacs package, written in Emacs-lisp, that provides direct access to installed BioPerl pod, and provides convenient and extendible template insertions. The package was designed to take advantage of modern elisp, and includes
- a clickable menu and tool bar interface;
- integrated BioPerl module and method name completion facilities;
- direct keystroke access to pod associated with identifiers beneath the cursor;
- readable, maintainable and extensible insertion templates in the form of elisp skeletons.
Development of bioperl-mode is motivated by some of the issues discussed in The Documentation Project, as an example of the kind of IDE support that could extend the working life of BioPerl. It makes the pod of the entire toolkit easily browsable without breaking stride, and, like the Emacs template, can save considerable typing effort while helping maintain BioPerl-standard formats.
RequirementsThe package currently requires Emacs 22. Emacs 21 compatibility was attempted, but shelved. If there is interest, I will make the attempt again, but you may want to consider upgrading. If you send me bugs (and this is encouraged), please inform me of your Emacs version, along with a description of what you were doing when the package borked. Send a debugger trace if available.
These are resolved.
- Multiple Bio library paths
- latest version (>= r16063) of distribution tar has this functionality
- Use the customize feature to set bioperl-module-path to include the desired paths, separated by the usual path delimiter for your OS. See below.
- Split and check invididual path components during PERL5LIB parsing
- fixed; now checks PATH for Bio modules, if PERL5LIB check fails
- Finding pod2text issue
- fixed; dependency on external pod2text removed in favor of a pure-elisp pod parser (pod.el)
I'm actively working on the following things:
- XEmacs support
- XEmacs beta can be tested; checkout as in Download and Install and untar bioperl-mode-xemacs.tar in your /usr/share/xemacs directory.
- Reliably providing the tool in the tool-bar
- Bioperl-view-mode keymap activation
Please help by reporting the issues on this work-in-progress!
Download and Install
Do a Subversion checkout of the distribution tarball:
$ svn co svn://code.open-bio.org/bioperl/bioperl-live/trunk/ide/bioperl-mode/dist bioperl-mode
which will get you a tarball and its MD5 signature (and maybe some cruft) in a new subdirectory called bioperl-mode.
Copy the tarball to your Emacs root directory. To find the root directory, start Emacs and type the following into the *scratch* buffer:
(replace-regexp-in-string "[^/]+/$" "" data-directory)
followed by ctrl-j (NOT return!). Note the result.
In the Emacs root, simply
$ tar -xf bioperl-mode.tar
Finally, in your .emacs file, add the line
(require 'bioperl-mode)near the top. You're done; no funky hooks to set or variables to define.
The source is available here.
bioperl-mode is a "minor mode", that can operate under any "major mode", such as text-mode, java-mode, or what have you. However, bioperl-mode is designed to infect the Perl major mode specifically, and transparently. Whenever perl-mode is invoked (usually automatically on opening a .pl or .pm file), bioperl-mode is enabled by default.
- To prevent auto-enabling of bioperl-mode, clear the customizing flag bioperl-mode-active-on-perl-mode-flag. Do
M-x describe-variable bioperl-mode-active-on-perl-mode-flag
- and click 'customize'.
- To toggle bioperl-mode on/off, do
- or click the bioperl-mode tool in the tool bar.
Setting the module search path
When bioperl-mode starts, it uses various means to find the paths that it will search in order to find the pod source. The paths it will use are stored in the variable bioperl-module-path, in a form similar to environment path variables like PATH or PERL5LIB on your system. For example, in linux the value might be
while in Windows, you may have
You can set bioperl-module-path using the Emacs customization features. In this case, lines are added to your .emacs file, and you can forget it. If the value isn't customized, then bioperl-mode will attempt to find your module paths in the following ways (in order):
- examine the BPMODE_PATH environment variable
- examine the PERL5LIB environment variable (choosing the paths that point to BioPerl modules)
- ask Perl itself for the site installation directory
- check the pwd for Bio modules
- carp and set bioperl-module-path to "."
Pod browsing and viewing
- Menu access
- When bioperl-mode is active, two pull-down menus will appear--"BP Docs" and "BP Templs", and [bio] shows up in the mode line.
- You can use the "BP Docs" menu to examine the pod. The pod viewing functions all are sensitive to the text underneath the cursor, but you can always backspace. Press [TAB] in the minibuffer (the text entry line) while entering to browse the possible completions.
- Sit back and read the pod. Pod viewing functions remain available in the pod view buffer.
- Completion tricks
The bioperl-mode completion facility will allow you to walk through the entire pod tree, from namespace to module to method. To activate completion, press [TAB] at any time in the minibuffer (the text entry area). See this sequence of screens and details below.
- View the source code
In pod view, press "f". You'll get a new buffer (in read-only view mode) containing the full source corresponding to the pod you're viewing.
In source view, you can jump to the sub definition of a given by using 'imenu', bound to the "i" key. Press "i", then enter the first few letters of the method name and TAB to complete, then press RETURN.
- View base classes
In pod view, press "B" or "P". You'll get a completion prompt in the mini-buffer, whose choices are the base classes of the current module whose pod you're visiting. (This is performed by scanning for use base or @ISA statements, so should be fairly complete. Please ping the author if you get unusual or incomplete results.)
- Keyboard shortcuts
Every pod viewing function is bound to a key sequence. As usual in Emacs, [ctrl-c] is pressed, then the key for the desired function. The key bindings are displayed next to items on the menu, or you can press [ctrl-h] [ctrl-m] in the Emacs buffer to see a table. If the default key bindings are not suitable, they can always be customized. Pod viewing functions are bound to alt key mnemonics; template insertion functions are bound to control key mnemonics.
[ctrl-c] [alt-p] View full pod for module [ctrl-c] [alt-d] View pod description section [ctrl-c] [alt-s] View pod synopsis section [ctrl-c] [alt-a] View pod appendix section [ctrl-c] [alt-m] View pod header for a particular method
Code template insertion
All the templates from Emacs template are available. New ones of your own devising should be added to bioperl-skel.el.
- Menu access
- Keyboard shortcuts
Template insertions are bound to control key mnemonics. The bindings in Emacs template have been preserved.
[ctrl-c] [ctrl-v] or [ctrl-c] [ctrl-a] Insert simple accessor template [ctrl-c] [ctrl-A] Insert object array accessor template [ctrl-c] [ctrl-M] or [ctrl-c] [ctrl-b] Insert Bioperl class/object template [ctrl-c] [ctrl-g] or [ctrl-c] [ctrl-k] Insert a generic package pod header template [ctrl-c] [ctrl-p] Insert a standard method pod header [ctrl-c] m Insert a module qualifier, with completion
bioperl-mode is designed to help you follow your nose as much as possible. Module name completion is enabled for all name-requiring inputs, and all such inputs are sensitive to the text near your cursor.
- Getting pod over multiple paths
bioperl-mode is designed to make its traversal of multiple paths (specified in bioperl-module-path) as transparent to the user as possible. Completion lists should include all modules or namespaces available over all paths specified. If an ambiguity arises (e.g., between Bio::Tools in bioperl-live and Bio::Tools in bioperl-run), the user can follow the desired path via completion, down to choosing the path if necessary. For this example, entering "Bio::Tools::Run" at the "Namespace" prompt will take you down bioperl-run, since that namespace does not exist in bioperl-live (assuming both paths are specified in bioperl-module-path; see Setting the module search path). The source directory from which the pod was read is indicated at the right end of the pod viewer header line.
This is the spec. Please ping me if the behavior you experience does not match this description.
- Getting pod from the pod
The pod view window is also bioperl-mode enabled. In any pod display, place the cursor on a BioPerl module identifier and hit RETURN. A new pod window will be created, displaying the pod for the selected module.
You can get a completion list of base classes for the module whose pod you're viewing by pressing "B" or "P" in pod view.
- Namespace/module amibiguities
The completion facility attempts to handle ambiguities intelligently. (Of course, it's only as intelligent as I am, so feel free to send me your complaints.) For example, Bio::SeqIO is a module in itself (Bio/SeqIO.pm), but also designates a namespace, containing Bio::SeqIO::fasta et al. If you request pod for the string Bio::SeqIO, you receive the following prompt:
[pod] Bio::SeqIO Module:
If you want pod for Bio/SeqIO/fasta.pm, enter "fasta" (or "f"-[TAB]) and proceed. If want pod for the module Bio/SeqIO.pm, hit [RETURN] at the prompt, to get the new prompt
[pod] Bio Module: SeqIO
(Yes, it has filled in the prompt for you.) Hit [RETURN] again to get pod for Bio::SeqIO.
If you want to back out to the Namespace prompt, enter blanks till you get there. For a non-ambiguous namespace, such as
[pod] Bio::SeqFeature Module:
hit [RETURN] to get
[pod] Namespace: Bio::SeqFeature
and complete away.
- Optionally fontify and electrify module names in perl code and pod
- Bind some fave functions to tool-bar tools
Emacs package standards
The code was written as closely as possible to the Emacs conventions. A few implications:
- Almost every identifier is prefixed with bioperl-. Do
M-x describe-variable bioperl-[TAB]
M-x describe-function bioperl-[TAB]
- to browse.
- Every variable and function has documentation.
- The mode can be unhooked from perl-mode at any time in an Emacs session by running bioperl-mode-unload-hooks.
Principles and decisions
- Parsing Pod
Pod content is obtained exclusively by accessing the user's installed Bioperl modules -- so it's as up-to-date as the user's installation.
Pod is parsed from source by a pure-elisp homebrew solution, called pod.el. It contains at least stubs for all standard pod keywords and formatters, but is not a complete pod parser (at the moment). The function pod-parse-buffer reduces source to pod, leaving the buffer looking like pod2text output.
Much of the parsing in this package depends on the standard form of Bioperl pod; particularly on the typical division into NAME, SYNOPSIS, DESCRIPTION, and APPENDIX sections, and on the fact that pod for individual methods is found in the APPENDIX. There is some dependence on the usual head levels for the headers, but this can be hacked out if necessary. A few well-placed hacks would make this package a general pod viewer.
Some attempts at efficiency were made. Parsing pod for methods and associated data can take a while, so parse results are cached for the last module so parsed, and the cache is checked when method information is requested before parsing again.
The Bio/ path is parsed to provide a namespace completion facility. The relevant path names and structure are stored in an alist tree called bioperl-module-names-cache. The cache is loaded lazily, so that the directory structure is accessed on a desire-to-know basis.
Lazy loading of the name cache necessitated "programmed completion" of namespace names in prompts. See Programmed Completion, and the function bioperl-namespace-completion-function.
Skeletons (implemented in the emacs standard package skeleton.el) are used for template insertions. These are very powerful (if cumbersome), offer plug-in interactor functions, and I think allow more modularity and scope for new additions than (insert)ing text "by hand". Skeletons and (define-skeleton) declarations are distributed in a separate file 'bioperl-skel.el', which is loaded when the mode is initialized.