Emacs bioperl-mode

From BioPerl
Jump to: navigation, search

Quick link to install. Latest distribution tar (04:03, 7 December 2009 (UTC)) is 16449; see Changelog.

New feature (r16445): Browse parent/base classes from pod view; press [B] or [P]

bioperl-mode in action

Check the known issues before reporting.

Happy Coding!

Contents


Abstract

bioperl-mode is a custom package for the Emacs editor that allows convenient BioPerl pod browsing and code template insertion.

Author

Mark A. Jensen

Fortinbras Research

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.

Motivation

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.

Requirements

The 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.
[back to top]


Known Issues

Repaired

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)

Active

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.
[back to top]


The source is available here.

Feature Walkthrough

Enabling bioperl-mode

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
M-x bioperl-mode
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

/usr/lib/perl5/site_perl/5.10:/usr/local/src/bioperl-live

while in Windows, you may have

c:/Perl/site/lib;c:/Users/Mark/bioperl/bioperl-live

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
[back to top]


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

The "BP Templs" menu lists the code/pod templates available. Follow the prompts to fill in the template.

  • 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

Completion features

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.

[back to top]


TODOs

  • Optionally fontify and electrify module names in perl code and pod
  • Bind some fave functions to tool-bar tools

Design Considerations

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]
and
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.

  • Caching

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

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.

[back to top]


Personal tools
Namespaces
Variants
Actions
Main Links
documentation
community
development
Toolbox