README

   1 * DESCRIPTION (-*- org -*-)
   2 Sepia is a set of features to make Emacs a better tool for Perl
   3 development, including:
   4
   5     * an interactive prompt (REPL) for evaluating code;
   6     * cross-referencing to find and navigate between function and
   7       variable definitions and uses;
   8     * variable- and function-name completion.
   9     * eldoc support to echo function arguments in the minibuffer
  10     * functions to simplify POD browsing with Emacs-w3m
  11
  12 I find Emacs as a software development environment preferable to many
  13 modern IDEs, particularly when using a richly-supported language like
  14 Lisp or Emacs Lisp.  Sepia is my attempt to give Perl a similar degree
  15 of support "in the Emacs way," which represents 40 years' collective
  16 experience of the software development community.  I have therefore
  17 tried throughout to use or mimic existing Emacs functionality, rather
  18 than to create something new.
  19
  20 * INSTALLATION
  21 Sepia is developed on (and probably requires) the latest version of
  22 GNU Emacs, which can be obtained from CVS or as a prebuilt package on
  23 some platforms.  All of its features could probably be made to work on
  24 other Emacsen, but some porting would be required.  The basic
  25 procedure is:
  26
  27     1) run "perl Makefile.PL; make; make install"
  28     2) optionally, install w3m and Emacs-w3m
  29     3) put the elisp files somewhere Emacs will find them.
  30
  31 ** Requirements for GNU Emacs 22
  32 *** (optional) emacs-w3m from http://emacs-w3m.namazu.org/
  33 *** (optional) w3m from http://w3m.sourceforge.net/
  34 ** Requirements GNU Emacs 21
  35 *** ido.el
  36     http://cvs.savannah.gnu.org/viewcvs/*checkout*/emacs/lisp/ido.el?root=emacs
  37 *** FreeBSD may require the following packages:
  38     tree-widget-emacs21-2.0
  39     emacs-w3m-emacs21-1.4.4_2
  40     mule-ucs-emacs21-0.85.r3
  41     semi-emacs21-1.14.6_1
  42     wv-1.2.4
  43     xlhtml-0.5_1,1
  44     libgsf-1.14.3
  45     flim-emacs21-1.14.8
  46     apel-emacs21-10.7
  47     ja-nkf-2.05
  48
  49 * GETTING STARTED
  50 To start the interpreter, type
  51
  52    M-x load-library RET sepia RET
  53    M-x sepia-init RET
  54
  55 Since the cross-reference database can take several seconds to create,
  56 and become outdated when the program changes, it must be built
  57 explicitly by
  58
  59    M-x sepia-rebuild RET
  60
  61 Type
  62
  63    C-h f sepia-init RET
  64
  65 to get a list of Sepia functions.  Locating functions will look up
  66 zero or more source locations, then allow you to cycle through them
  67 with "M-x sepia-next" ("\M-," by default).  With a prefix argument,
  68 the functions will instead display a grep-mode buffer listing all the
  69 hits.
  70 * COMMANDS
  71 ** Navigation and text manipulation
  72 *** `C-M-a' (`sepia-beginning-of-defun')
  73 Move to beginning of current function.
  74
  75 If prefix argument given, move n functions backward.
  76
  77 *** `C-M-e' (`sepia-end-of-defun')
  78 Move to beginning of current function.
  79
  80 If prefix argument given, move n functions forward.
  81
  82 ** Symbol completion
  83 *** `M-TAB' (`sepia-complete-symbol')
  84 Try to complete the word at point, either as a global variable if it
  85 has a sigil (sorry, no lexicals), a module, or a function.  The
  86 function currently ignores module qualifiers, which may be
  87 annoying in larger programs.
  88
  89 *** (`sepia-ido-complete')
  90 Try to complete the current pattern amongst the file names.
  91
  92 *** `TAB' (`sepia-indent-or-complete')
  93 Indent the current line and, if indentation doesn't move point,
  94 complete the symbol around point.
  95
  96 ** Evaluation
  97 *** `C-M-x' (`sepia-eval-defun')
  98 Re-evaluate the current function and rebuild its Xrefs.
  99
 100 *** `C-c C-l' (`sepia-load-file')
 101 Reload the current buffer's file into the interpreter.  With rebuild-p
 102 (or a prefix argument when called interactively), also rebuild the
 103 xref database.
 104
 105 ** Scratchpad and REPL
 106 *** (`sepia-scratch')
 107 Create a buffer to interact with a Perl interpreter.
 108
 109 The buffer is placed in cperl-mode; calling
 110 ``sepia-scratch-send-line'' will evaluate the current line and
 111 display the result.
 112
 113 *** `C-j' (`sepia-scratch-send-line')
 114 Send the current line to Perl, and display the result.
 115
 116 *** (`sepia-interact')
 117 Start or switch to a Perl interaction buffer.
 118
 119 ** Finding definitions and uses
 120 *** `M-. KEY' keys
 121     M-.             sepia-dwim
 122     l               sepia-location
 123     a               sepia-apropos
 124     A               sepia-var-apropos
 125     f               sepia-defs
 126     c               sepia-callers
 127     C               sepia-callees
 128     v               sepia-var-uses
 129     V               sepia-var-defs
 130     m               sepia-module-find
 131     d               sepia-w3m-perldoc-this
 132     j               sepia-jump-to-symbol
 133     n               sepia-next
 134     r               sepia-rebuild
 135     t               find-tag
 136
 137 With a prefix argument, these functions list occurences in a
 138 ``grep-mode'' buffer.  Without, they place the occurrences on
 139 ``sepia-found'', then go to the first; calling ``sepia-next'' will
 140 cycle through the other locations.
 141
 142 Depending on the query, module, file, and line information may be used
 143 to narrow the results, as long as doing so leaves some matches.
 144
 145 Note that `find-tag', the normal binding of `M-.', is still available
 146 on `M-. t'.
 147
 148 *** `M-,' `M-. n' (`sepia-next')
 149 Go to the next thing (e.g. def, use) found by a previous sepia
 150 command.
 151
 152 *** (`sepia-location')
 153 Go to a named function's definition.
 154
 155 *** `M-. r' (`sepia-rebuild')
 156 Rebuild the Xref database.
 157
 158 *** `M-.' (`sepia-dwim')
 159 Try to do the right thing with identifier at point:
 160     * Find all definitions, if thing-at-point is a function
 161     * Find all uses, if thing-at-point is a variable
 162     * Find documentation, if thing-at-point is a module
 163     * Prompt otherwise
 164
 165 ** Miscellany
 166 *** (`sepia-init')
 167 Perform the initialization necessary to start Sepia, a set of
 168 tools for developing Perl in Emacs.
 169
 170 *** (`sepia-doc-update')
 171 Update documentation for a file.
 172
 173 This documentation, taken from "=item" entries in the POD, is
 174 used for eldoc feedback.
 175
 176 *** (`sepia-display-errors')
 177 Display source causing errors in current buffer.
 178
 179 *** (`sepia-goto-error-at')
 180 Visit the source of the error on line at point.
 181
 182 *** (`sepia-install-eldoc')
 183
 184 Install Sepia hooks for eldoc support.
 185
 186 *** (`sepia-install-keys')
 187
 188 Install Sepia bindings in the current local keymap.
 189
 190 *** (`sepia-module-describe' / `sepia-package-defs')
 191 Find all subroutines in a package.
 192
 193 ** Documentation browsing
 194 *** (`sepia-perldoc-this')
 195 View perldoc for module at point.
 196
 197 *** (`sepia-view-pod')
 198 View POD for the current buffer.
 199
 200 *** (`sepia-package-list')
 201 List installed packages in an HTML page, with links to the
 202 documentation of their top-level modules.
 203
 204 *** (`sepia-module-list')
 205 List installed modules in an HTML page, grouped by package, with links
 206 to their documentation.
 207
 208 ** Tree browsing (somewhat flaky)
 209 Pressing RET on a function's name displays its definition.  With
 210 prefix argument, RET instead visits in another window.
 211
 212 *** (`sepia-callee-tree')
 213 Create a tree view of a function's callees.
 214
 215 *** (`sepia-caller-tree')
 216 Create a tree view of a function's callers.
 217
 218 *** (`sepia-module-callee-tree')
 219 Display a callee tree for each of mod's subroutines.
 220
 221 ** User variables
 222 *** sepia-prefix-key (default: "\M-.")
 223 Prefix for functions in ``sepia-keymap''.
 224
 225 *** sepia-perl5lib (default: nil)
 226 Extra PERL5LIB directory for Sepia.pm
 227
 228 *** sepia-eval-defun-include-decls (default: t)
 229 Generate and use a declaration list for ``sepia-eval-defun''.
 230
 231 *** sepia-program-name (default: "perl")
 232 Perl program name.
 233
 234 *** sepia-use-completion (default: t)
 235 Use completion based on Xref database.  Turning this off may speed up
 236 some operations, if you don't mind losing completion.
 237
 238 * TODO
 239 ** implement mod_apropos
 240 ** use xref-completions in sepia-interactive-arg
 241 ** improve output for sepia-module-* (modinfo functions)
 242 ** better intro for debugger
 243 ** (Easy) Use module, file, line to refine queries (Perl side)
 244 ** (Medium) Get the variable def/use analysis working again.
 245 ** (Medium) Support user-defined abbrevs in REPL
 246 ** (Easy) Clean up Perl side a bit more.
 247 ** (Hard) Use module, file, line to filter results (Emacs side)
 248 ** (Medium) Let sepia-next go backward
 249    Need to use a vector plus current index instead of a list for
 250    sepia-found.
 251 ** (Medium) Use lexical environment more
 252    ",eval" should use lexical evaluation whenever PadWalker's available.
 253 ** (Hard) return from anything in the debugger
 254    Make it possible to return from intermediate calls in the
 255    debugger.  Returning from die() is not often useful.
 256 ** (Easy) Fix sepia-indent-or-complete abbrev expansion
 257    Currently "else<TAB>" both expands and completes.
 258 ** (Medium) Clean up Sepia::completions et al.
 259 * BUGS
 260 ** Function definition lines may occasionally all go completely wrong.
 261    Rebuilding the Xref database fixes this.
 262 ** The cursor may miss by several lines when jumping to a definition.
 263    This is hard to fix -- Perl doesn't give exact line numbers for sub
 264    defs, so we have to do some minor regex-searching.
 265 ** `sepia-var-assigns' doesn't work yet -- don't use it.
 266 ** named method calls are (mostly?) detected, but nothing smart is
 267    done about packages, so e.g. "new Foo" will result in listings for
 268    every instance of "new" in your program.
 269 ** `sepia-beginning-of-defun' and `sepia-end-of-defun' are flaky.
 270    Specifically, while they work for "normal" sub definitions, they
 271    fail on definitions that are all on one line, e.g.
 272
 273        sub foo { ... }
 274        sub bar {
 275            ...
 276        }
 277 * CREDITS
 278 Sepia would never have been possible without Software Libre, as many
 279 key components have been stolen and adapted from other packages:
 280
 281     * Sepia::Xref is taken from B::Xref.
 282     * sepia-w3m is taken from w3m-perldoc.
 283 * COPYRIGHT AND LICENCE
 284 Copyright (C) 2004-2007 by Sean O'Rourke
 285
 286 This library is free software; you can redistribute it and/or modify
 287 it under the same terms as Perl itself, at the time at which this
 288 version of Sepia was released.