* DESCRIPTION (-*- org -*-) Sepia is a set of features to make Emacs a better tool for Perl development, including: * an interactive prompt (REPL) for evaluating code; * cross-referencing to find and navigate between function and variable definitions and uses; * variable- and function-name completion. * eldoc support to echo function arguments in the minibuffer * functions to simplify POD browsing with Emacs-w3m Please see the Sepia.html or sepia.info for documentation. * INSTALLATION The basic installation procedure is: 1) run "perl Makefile.PL; make; make install" 2) optionally, install w3m and Emacs-w3m 3) put the elisp files somewhere Emacs will find them. Sepia is developed on the latest version of GNU Emacs, which can be obtained from CVS or as a prebuilt package on some platforms. It can run on other versions of Emacs, but may require additional packages. ** Requirements for GNU Emacs 22 *** (optional) emacs-w3m from http://emacs-w3m.namazu.org/ *** (optional) w3m from http://w3m.sourceforge.net/ *** (optional) snippet.el from http://www.kazmier.com/computer/snippet.el ** Additional requirements GNU Emacs 21 *** ido.el http://cvs.savannah.gnu.org/viewcvs/*checkout*/emacs/lisp/ido.el?root=emacs *** FreeBSD may require the following packages: tree-widget-emacs21-2.0 emacs-w3m-emacs21-1.4.4_2 mule-ucs-emacs21-0.85.r3 semi-emacs21-1.14.6_1 wv-1.2.4 xlhtml-0.5_1,1 libgsf-1.14.3 flim-emacs21-1.14.8 apel-emacs21-10.7 ja-nkf-2.05 * DEVELOPMENT The "official" source code repository mirror is at http://repo.or.cz/w/sepia.git To get a copy, install Git, then git clone git://repo.or.cz/sepia.git To submit a patch, please send a diff to the author, including an Emacs-style ChangeLog entry. * TODO ** (Medium) Get the variable def/use analysis working again. ** (Hard) return from anything in the debugger Make it possible to return from intermediate calls in the debugger. Returning from die() is not often useful. This can be done with a clever DB::sub, but that dramatically slows down execution. ** (Medium) fix `sepia-beginning-of-defun' and `sepia-end-of-defun'. While they work for "normal" sub definitions, they fail on definitions that are all on one line, e.g. sub foo { ... } sub bar { ... } ** (Medium) Fix string escaping when passing between Perl and Emacs IO::Scalar's README tickles a bug. ** (Hard) Make the debugger's "next" work "next" (as opposed to "step") assumes that the next statement after line $n is line $n+1, which isn't true for loops, blank lines, multi-line statements, etc. Fix this somehow. One way might be to temporary regain control on a op_next/op_nextstate, or whatever those are called, but this would be hard and/or require XS. If we set $^P to populate @dbline, we can use that to find breakable lines, but that still doesn't fix backward branches in loops. ** (Medium) Make "finish" more reliable It currently assumes that the last breakable statement in a sub is one line before its end. The "right" solution would be like above: to hook op_leave temporarily. This would similarly require XS trickery. ** (Medium) Enable partial-word completion of lexicals ** (Hard) Rewrite completion code, which is pretty ugly now. This wouldn't seem "hard" but, having hacked on two completion codebases (Sepia's and complete.el's), I know there are always a lot of subtle cases to get right, and what acts "naturally" by human standards is extremely complicated to specify in code. ** (Easy) Document existing hooks and add_hook()/remove_hook() @PRE_PROMPT, @PRE_EVAL, @POST_EVAL ** (Hard) Add appropriate hooks Possibly update existing functions to make use of hooks for better modularity. * KNOWN BUGS The following is a list of bugs that are difficult to automatically reproduce, with the dates they were first observed. ** (2006-05-19) Function definition lines occasionally all go wrong. Rebuilding the Xref database fixes this. ** (2006-05-19) The cursor misses by several lines jumping to a definition. This is hard to fix -- Perl doesn't give exact line numbers for sub defs, so we have to do some minor regex-searching. ** (2006-05-19) `sepia-var-assigns' doesn't work yet -- don't use it. ** (2006-05-19) named method calls (mostly?) detected, but naively. Nothing smart is done about packages, so e.g. "new Foo" will result in listings for every instance of "new" in your program. ** (2008-01-18) the first value printed in the debugger is undef. why?! ** (2009-12-13) completion deletes things it shouldn't e.g. $x->method => method. I need to rewrite this code to not suck. ** (2010-09-30) broken in view-mode should scroll up if you enable view-mode, but for whatever reason it stays bound to hungry-delete. I'm not sure if this is my fault, or cperl's. ** (2011-02-22) Sepia::Xref::load_pad segfaults While traversing inside File::Find::contract_name. Backtrace: #0 0x00000001001afa30 in XS_B__COP_hints_hash () #1 0x00000001001b12ba in XS_B__GV_STASH () #2 0x0000000100075708 in Perl_pp_entersub () #3 0x000000010006e6cc in Perl_runops_standard () #4 0x000000010006e43a in perl_run () * COPYRIGHT AND LICENCE Copyright (C) 2004-2011 Sean O'Rourke This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself, at the time at which this version of Sepia was released.