README
1* DESCRIPTION (-*- org -*-)
2Sepia is a set of features to make Emacs a better tool for Perl
3development, 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
12Please see the Sepia.html or sepia.info for documentation.
13* INSTALLATION
14The basic installation procedure is:
15
16 1) run "perl Makefile.PL; make; make install"
17 2) optionally, install w3m and Emacs-w3m
18 3) put the elisp files somewhere Emacs will find them.
19
20Sepia is developed on the latest version of GNU Emacs, which can be
21obtained from CVS or as a prebuilt package on some platforms. It can
22run on other versions of Emacs, but may require additional packages.
23** Requirements for GNU Emacs 22
24*** (optional) emacs-w3m from http://emacs-w3m.namazu.org/
25*** (optional) w3m from http://w3m.sourceforge.net/
26*** (optional) snippet.el from http://www.kazmier.com/computer/snippet.el
27** Additional requirements GNU Emacs 21
28*** ido.el
29 http://cvs.savannah.gnu.org/viewcvs/*checkout*/emacs/lisp/ido.el?root=emacs
30*** FreeBSD may require the following packages:
31 tree-widget-emacs21-2.0
32 emacs-w3m-emacs21-1.4.4_2
33 mule-ucs-emacs21-0.85.r3
34 semi-emacs21-1.14.6_1
35 wv-1.2.4
36 xlhtml-0.5_1,1
37 libgsf-1.14.3
38 flim-emacs21-1.14.8
39 apel-emacs21-10.7
40 ja-nkf-2.05
41
42* DEVELOPMENT
43The "official" source code repository mirror is at
44
45 http://repo.or.cz/w/sepia.git
46
47To get a copy, install Git, then
48
49 git clone git://repo.or.cz/sepia.git
50
51To submit a patch, please send a diff to the author, including an
52Emacs-style ChangeLog entry.
53* TODO
54** (Medium) Get the variable def/use analysis working again.
55** (Hard) return from anything in the debugger
56 Make it possible to return from intermediate calls in the debugger.
57 Returning from die() is not often useful.
58
59 This can be done with a clever DB::sub, but that dramatically slows
60 down execution.
61** (Medium) fix `sepia-beginning-of-defun' and `sepia-end-of-defun'.
62 While they work for "normal" sub definitions, they fail on
63 definitions that are all on one line, e.g.
64
65 sub foo { ... }
66 sub bar {
67 ...
68 }
69** (Medium) Fix string escaping when passing between Perl and Emacs
70 IO::Scalar's README tickles a bug.
71** (Hard) Make the debugger's "next" work
72 "next" (as opposed to "step") assumes that the next statement after
73 line $n is line $n+1, which isn't true for loops, blank lines,
74 multi-line statements, etc. Fix this somehow. One way might be to
75 temporary regain control on a op_next/op_nextstate, or whatever
76 those are called, but this would be hard and/or require XS.
77
78 If we set $^P to populate @dbline, we can use that to find
79 breakable lines, but that still doesn't fix backward branches in
80 loops.
81** (Medium) Make "finish" more reliable
82 It currently assumes that the last breakable statement in a sub is
83 one line before its end. The "right" solution would be like above:
84 to hook op_leave temporarily. This would similarly require XS
85 trickery.
86** (Medium) Enable partial-word completion of lexicals
87** (Hard) Rewrite completion code, which is pretty ugly now.
88 This wouldn't seem "hard" but, having hacked on two completion
89 codebases (Sepia's and complete.el's), I know there are always a
90 lot of subtle cases to get right, and what acts "naturally" by
91 human standards is extremely complicated to specify in code.
92** (Easy) Document existing hooks and add_hook()/remove_hook()
93@PRE_PROMPT, @PRE_EVAL, @POST_EVAL
94** (Hard) Add appropriate hooks
95 Possibly update existing functions to make use of hooks for better
96 modularity.
97* KNOWN BUGS
98The following is a list of bugs that are difficult to automatically
99reproduce, with the dates they were first observed.
100** (2006-05-19) Function definition lines occasionally all go wrong.
101 Rebuilding the Xref database fixes this.
102** (2006-05-19) The cursor misses by several lines jumping to a definition.
103 This is hard to fix -- Perl doesn't give exact line numbers for sub
104 defs, so we have to do some minor regex-searching.
105** (2006-05-19) `sepia-var-assigns' doesn't work yet -- don't use it.
106** (2006-05-19) named method calls (mostly?) detected, but naively.
107 Nothing smart is done about packages, so e.g. "new Foo" will result
108 in listings for every instance of "new" in your program.
109** (2008-01-18) the first value printed in the debugger is undef. why?!
110** (2009-12-13) completion deletes things it shouldn't
111 e.g. $x->method => method. I need to rewrite this code to not
112 suck.
113** (2010-09-30) <backspace> broken in view-mode
114 <backspace> should scroll up if you enable view-mode, but for
115 whatever reason it stays bound to hungry-delete. I'm not sure if
116 this is my fault, or cperl's.
117** (2011-02-22) Sepia::Xref::load_pad segfaults
118While traversing inside File::Find::contract_name. Backtrace:
119 #0 0x00000001001afa30 in XS_B__COP_hints_hash ()
120 #1 0x00000001001b12ba in XS_B__GV_STASH ()
121 #2 0x0000000100075708 in Perl_pp_entersub ()
122 #3 0x000000010006e6cc in Perl_runops_standard ()
123 #4 0x000000010006e43a in perl_run ()
124* COPYRIGHT AND LICENCE
125Copyright (C) 2004-2011 Sean O'Rourke
126
127This library is free software; you can redistribute it and/or modify
128it under the same terms as Perl itself, at the time at which this
129version of Sepia was released.
130