1 \input texinfo @c -*-texinfo-*-
3 @setfilename sepia.info
4 @settitle SEPIA: Simple Emacs Perl Integration
7 * Sepia: (sepia). Simple Emacs Perl Integration.
12 @title Sepia: Simple Emacs Perl Integration
16 @macro kbinding{key,cmd}
30 @node Top, Introduction, (dir), (dir)
40 Sepia is a set of Perl development tools for Emacs supporting code
41 navigation and interactive evaluation.
53 @c ============================================================
54 @node Introduction, Editing, Top, Top
57 Sepia is a set of tools for Perl development in Emacs. Its goal is to
58 extend CPerl mode to support fast code navigation and interactive
59 development. It is inspired by Emacs' current support for a number of
60 other languages, including Lisp, Python, and Emacs Lisp.
67 @node Getting Started, Philosophy, Introduction, Introduction
68 @section Getting Started
70 To install Sepia, its Emacs Lisp files must be in Emacs'
71 @code{load-path}, and the @file{lib} directory must be in Perl's
72 @code{@@INC}. Assuming that Sepia has been unpacked in
73 @file{~/sepia}, it can be installed by adding the following lines to
77 (add-to-list 'load-path "~/sepia")
78 (setq sepia-perl5lib (list (expand-file-name "~/sepia/lib")))
79 (defalias 'perl-mode 'sepia-mode)
83 Then to bring up the interactive Perl prompt, type @kbd{M-x sepia-repl}.
85 @node Philosophy, , Getting Started, Introduction
88 A development environment should support three activities: code
89 spelunking, interaction, and customization. Emacs as an environment for
90 developing Emacs Lisp thoroughly supports all of them: It has commands
91 to visit individual functions' code and documentation, commands to
92 evaluate or step through expressions, and an architecture that
93 encourages customization in Emacs Lisp. As an environment for Perl,
94 however, it is lacking: there is limited interactivity with the Perl
95 debugger, and reasonable documentation browsing, but no support for
96 navigating, editing, and re-evaluating code. Sepia attempts to remedy
99 Modern IDEs also support these three activities, but do so awkwardly.
100 Rather than having functions to visit definitions (@kbd{find-function})
101 and search for functions (@kbd{apropos}), they clutter the screen with
102 class and file trees. Rather than supporting interactive evaluation of
103 small pieces of code, they perform background semantic checking on whole
104 projects and highlight errors. Rather than allowing minor
105 customizations to grow organically into features, they support limited
106 configuration files and baroque plug-in APIs. Sepia tries to adhere to
107 the apparent Emacs philosophy that rich semantic information should be
108 unobtrusive, and that the best way to build working code is to start
109 by experimenting with small pieces.
111 Language support packages for Emacs vary widely in the degree to which
112 they make use of or replace existing Emacs features. Minimal modes
113 provide keyword-based syntax highlighting and an unadorned comint buffer
114 as an interpreter. Others provide their own specialized equivalents of
115 comint, eldoc, completion, and other Emacs features. Sepia takes a
116 third approach by trying to do as much as possible with existing Emacs
117 features, even when they are not optimal for Perl. For example, it uses
118 comint to communicate with the subprocess, eldoc to display
119 documentation, and grep to list source locations.
121 This approach has three advantages: First, it maximizes the number of
122 features that can be supported with limited development time. Second,
123 it respects users' settings. A seasoned Emacs user may have changed
124 hundreds of settings, so a mode that reimplements features will have to
125 support equivalent settings, and will force the user to re-specify them.
126 Finally, this approach respects decades of development spent, as Neal
127 Stephenson put it, ``focused with maniacal intensity on the deceptively
128 simple-seeming problem of editing text.'' Many non-obvious choices go
129 into making a polished interface, and while a reimplementation gets rid
130 of accumulated cruft, it must rediscover these hidden trade-offs.
132 Anyways, I hope you enjoy using Sepia. Its development style is strange
133 for someone used Perl's typical mix of one-liners and edit-save-run, but
134 once you are accustomed to it, you may find it very effective.
136 @c ============================================================
137 @node Editing, Interactive Perl, Introduction, Top
141 Sepia's first contribution is a set of commands to explore a Perl
142 codebase. These include commands to browse and display documentation,
143 to find function definitions, and to query a cross-reference database of
144 function and variable uses. Sepia also provides intelligent symbol
153 @node Completion, Navigation, Editing, Editing
156 Sepia implements partial-word completion that communicates with the
157 inferior Perl process. For example, @samp{%S:X:v_u} completes to
158 @samp{%Sepia::Xref::var_use} when Sepia is loaded. This completion only
159 operates on functions and global variables known to the Perl
160 interpreter, so it works best when code and interpreter are in sync.
162 More precisely, completion examines the text before point and tries each
163 of the following in turn, using the first successful approach:
167 If the text looks like a method call (e.g. @samp{$object->f} or
168 @samp{Class->f}), complete on methods.
171 If it looks like a variable (e.g. @samp{%hash} or @samp{$scalar}),
172 complete on variables.
175 Complete on modules and functions.
178 Otherwise, complete on Perl built-in operators.
181 For each of the first three cases, completions candidates are first
182 generated by splitting the text on characters @code{[:_]} and matching
183 the resulting word parts. For example, @samp{X:a_b} will complete to
184 all symbols matching @samp{^X[^:]*:+a[^:_]*_b} such as @samp{Xref::a_bug}
185 and @samp{X::always_bites_me}. If no matches result, the text is
186 treated as an acronym. For example, @samp{dry} will complete to
187 @samp{dont_repeat_yourself}.
189 Completion is performed by the following commands:
191 @item M-x sepia-complete-symbol
192 @findex sepia-complete-symbol
193 Complete the symbol before point as described above. Note that this
194 does not consider lexical scope, and is always case-sensitive,
195 independent of @code{completion-ignore-case}.
198 @itemx M-x sepia-indent-or-complete
199 @findex sepia-indent-or-complete
200 First try to reindent the current line. If its indentation does not
201 change, then try to expand an abbrev at point (unless
202 @code{sepia-indent-expand-abbrev} is @code{nil}). If no abbrev is
203 expanded, then call @code{sepia-complete-symbol}.
207 @node Navigation, Documentation, Completion, Editing
210 Sepia provides several commands for navigating program source. All of
211 them rely on information from the inferior Perl process, so it is
212 important both that it be running, and that its internal representation
213 of the program match the program source. The commands marked (Xref)
214 below also rely on a cross-reference database, which must be explicitly
215 rebuilt by calling @code{xref-rebuild} when the program changes.
217 There are two basic kinds of navigation commands. The first kind jumps
218 directly to the first matching location when possible, prompting only if
219 no such location is found. These commands find only a single location.
221 @c direct-jump commands
225 @itemx M-x sepia-dwim
227 Guess what kind of identifier is at point, and try to do the right
228 thing: for a function, find its definition(s); for a variable, find its
229 uses; for a module, view its documentation; otherwise, prompt for the
230 name of a function to visit. @code{sepia-dwim} automatically goes to
231 the first function definition or variable use found.
234 @itemx M-x sepia-location
235 @findex sepia-location
236 Jump directly to the definition of the function at point, prompting if
237 point is not on a known function. If multiple definitions are found,
238 choose one arbitrarily. This function is similar to @code{sepia-defs},
239 and the two should probably be merged.
242 @itemx M-x sepia-jump-to-symbol
243 @findex sepia-jump-to-symbol
244 Navigate to a function using ``ido'' interactive completion. Within
245 interactive completion, press @key{:} to descend into a package,
246 @key{DEL} to ascend to a parent package, and @key{RET} to go to the
247 currently-selected function.
251 The second kind of navigation commands always prompts the user -- though
252 usually with a sensible default value -- and finds multiple locations.
253 When called with a prefix argument, these commands present their results
254 in a @code{grep-mode} buffer. When called @emph{without} a prefix
255 argument, they place all results on the found-location ring and jump
256 directly to the first. The remaining locations can be cycled through by
257 calls to @code{sepia-next}.
259 @c prompt-and-go commands
261 @item M-. f @var{name} @key{RET}
262 @itemx M-x sepia-defs
264 Find definition(s) of function @var{name}.
266 @item M-. m @var{name} @key{RET}
267 @itemx M-x sepia-module-find @var{name} @key{RET}
268 @findex sepia-module-find
269 Find the source of module @var{name}.
271 @item M-. a @var{regexp} @key{RET}
272 @itemx M-x sepia-apropos @var{regexp} @key{RET}
273 @findex sepia-apropos
274 Find definitions of all functions whose names match @var{regexp}.
276 @item M-. c @var{name} @key{RET}
277 @itemx M-x sepia-callers @var{name} @key{RET}
278 @findex sepia-callers
279 (Xref) Find calls to function @var{name}.
281 @item M-. C @var{name} @key{RET}
282 @itemx M-x sepia-callees @var{name} @key{RET}
283 @findex sepia-callees
284 (Xref) Find the definitions of functions called by @var{name}.
286 @item M-. v @var{name} @key{RET}
287 @itemx M-x sepia-var-uses @var{name} @key{RET}
288 @findex sepia-var-uses
289 (Xref) Find uses of the global variable @var{name}.
291 @item M-. V @var{name} @key{RET}
292 @itemx M-x sepia-var-defs @var{name} @key{RET}
293 @findex sepia-var-defs
294 (Xref) Find definitions of global variable @var{name}. Since Perl's
295 global variables are not declared, this is rarely useful
297 @c XXX: broken, so don't mention it.
298 @c @item M-. A @var{regexp} @key{RET}
299 @c @itemx M-x sepia-var-apropos
300 @c @findex sepia-var-apropos
301 @c Find definitions of all variables whose names match @var{regexp}. Since
302 @c this function does not handle lexical variables, and since Perl's global
303 @c variables are not declared, this is rarely useful.
307 Finally, there are several other navigation-related commands that do not
308 fit into either of the above categories.
313 @itemx M-x sepia-next
315 Cycle through the definitions found by the previous @key{M-.} search.
318 @itemx M-x sepia-rebuild
319 @findex sepia-rebuild
320 Rebuild the cross-reference database by walking the op-tree and
325 Execute the @code{find-tag} command typically bound to @key{M-.}.
329 @node Documentation, , Navigation, Editing
330 @section Documentation
332 Sepia can be used to browse installed modules' documentation, to format
333 and display the current buffer's POD, and to browse the list of modules
334 installed on the system.
337 @item M-. d @var{name} @key{RET}
338 @itemx M-x sepia-perldoc-this
339 @findex sepia-perldoc-this
340 View documentation for module @var{name} or Perl manual page @var{name}.
343 @itemx M-x sepia-view-pod
344 @findex sepia-view-pod
345 Format and view the current buffer's documentation.
347 @item sepia-package-list
348 @findex sepia-package-list
349 Browse a tree of installed packages. This lists only the top-level
350 packages from installed distributions, so if package @code{My::Stuff}
351 also provides @code{My::Stuff::Details}, it will not be displayed. When
352 Emacs-w3m is available, each module is linked to its documentation.
354 @item sepia-module-list
355 @findex sepia-module-list
356 Browse a tree of both top-level and internal packages, like
357 @code{sepia-package-list}.
361 @findex sepia-install-eldoc
362 Sepia also integrates with eldoc (at least in GNU Emacs >= 22).
363 Documentation for Perl operators and control structures is taken from
364 CPerl mode. Sepia will also display documentation for user-defined
365 functions if their POD is formatted in the standard way, with functions
366 described in a ``=head2'' or ``=item'' entry. To load user
367 documentation, visit the relevant file and type @kbd{M-x
370 If @code{Module::CoreList} is available, Sepia's eldoc function will
371 also display the first version of Perl with which a module was shipped.
372 This is intended to give the programmer a sense of when he is creating
373 external dependencies.
375 @c ============================================================
376 @node Interactive Perl, Customization, Editing, Top
377 @chapter Interactive Perl
380 Sepia's second main contribution is an interactive interface (REPL) to
381 an inferior Perl process. The interface is based on GUD mode, and
382 inherits many of its bindings; this chapter discusses only the Sepia
383 extensions. To start or switch to the repl, type @kbd{M-x sepia-repl}.
384 As in Sepia mode, @key{TAB} in the REPL performs partial-word completion
385 with @code{sepia-complete-symbol}.
387 Sepia also provides a number of other ways to evaluate pieces of code in
388 Perl, and commands to process buffer text using the inferior process.
398 @node Shortcuts, Debugger, Interactive Perl, Interactive Perl
401 ``Shortcuts'' are commands handled specially by the REPL rather than
402 being evaluated as Perl code. They either communicate with the REPL
403 function, or provide a convenient interface to variables in the Sepia
404 package. Shortcuts are prefixed by a comma (@key{,}), and may be
405 abbreviated to the shortest unique prefix.
409 Change Perl's current directory to @var{dir}.
411 @item debug [@var{val}]
412 Turn Sepia debugger hook on or off, or toggle if @var{val} is missing.
414 @item define @var{name} ['@var{doc}'] @var{body...}
415 Define @var{name} as a shortcut for Perl code @var{body}, with optional
416 documentation @var{doc}, surrounded by single quotes. @var{body} is
417 passed the raw command-line text as its first argument.
420 Delete the current breakpoint.
422 @item format @var{type}
423 Set the output format to @var{type}, either ``dumper'' (using
424 @code{Data::Dumper}), ``dump'' (@code{Data::Dump}), ``yaml''
425 (@code{YAML}), or ``plain'' (stringification). Default: ``dumper''.
428 Display a list of shortcuts.
433 @item methods @var{name} [@var{regexp}]
434 Display a list of functions defined in package @var{name} and its
435 @code{ISA}-ancestors matching optional pattern @var{regexp}.
437 @item package @var{name}
438 Set the default evaluation package to @var{name}.
441 Show the process's current working directory.
444 Exit the inferior Perl process.
447 Reload @file{Sepia.pm} and recursively invoke the REPL. This command is
448 mostly of interest when working on Sepia itself.
450 @item shell [@var{command}]
451 Execute shell command @var{command}, displaying its standard output and
454 @item strict [@var{val}]
455 Set evaluation strictness to @var{val}, or toggle it if @var{val} is not
456 given. Note that turning strictness off and on clears the REPL's
459 @item undef @var{name}
460 Undefine shortcut @var{name}. @strong{Warning}: this can equally be
461 used to remove built-in shortcuts.
463 @item wantarray [@var{val}]
464 Set the evaluation context to @var{val}, or toggle between scalar and
467 @item who @var{package} [@var{regexp}]
468 @itemx who [@var{regexp}]
469 List identifiers in @var{package} (main by default) matching
470 optional @var{regexp}.
474 @node Debugger, Evaluation, Shortcuts, Interactive Perl
477 Sepia uses Perl's debugger hooks and GUD mode to support conditional
478 breakpoints and single-stepping, and overrides Perl's @code{die()} to
479 invoke the debugger rather than unwind the stack. This makes it
480 possible to produce a backtrace, inspect and modify global variables,
481 and even continue execution when a program tries to kill itself. If the
482 PadWalker module is available, Sepia also provides functions to inspect
483 and modify lexical variables.
485 The debugger has its own set of shortcuts, also prefixed by a comma.
491 @item break @var{file}:@var{line} [@var{expr}]
492 Set a breakpoint in @var{file} at @var{line}. If @var{expr} is
493 supplied, stop only if it evaluates to true.
497 Move the current stack frame up or down by @var{n} (or one) frames.
499 @item inspect [@var{n}]
500 Inspect lexicals in the current frame or frame @var{n}, counting upward
507 Advance @var{n} (or one) lines, skipping subroutine calls.
512 Continue as the program would have executed without debugger
513 intervention, dying if the debugger was called from @code{die()}.
515 @item return @var{expr}
516 Continue execution as if @code{die()} had returned the value of
517 @var{expr}, which is evaluated in the global environment.
520 Step forward @var{n} (or one) lines, descending into subroutines.
524 @node Evaluation, Mutilation, Debugger, Interactive Perl
527 When interactive Perl is running, Sepia can evaluate regions of code in
528 the inferior Perl process. The following commands assume that this
529 process has already been started by calling @code{sepia-repl}.
533 @itemx M-x sepia-eval-defun
534 @findex sepia-eval-defun
535 Evaluate the function around point in the inferior Perl process. If it
536 contains errors, jump to the location of the first.
539 @itemx M-x sepia-load-file
540 @findex sepia-load-file
541 Save the current buffer, then reload its file and if warnings or errors
542 occur, display an error buffer. With a prefix argument, also rebuild
543 the cross-reference index.
546 @itemx M-x sepia-eval-expression @key{RET} @var{expr} @key{RET}
547 @findex sepia-eval-expression
548 Evaluate @var{expr} in scalar context and echo the result. With a
549 prefix argument, evaluate in list context.
553 Set the REPL's working directory to the current buffer's directory.
557 @node Mutilation, Scratchpad, Evaluation, Interactive Perl
560 Sepia contains several functions to operate on regions of text using the
561 interactive Perl process. These functions can be used like standard
562 one-liners (e.g. @samp{perl -pe ...}), with the advantage that all of
563 the functions and variables in the interactive session are available.
566 @item M-x sepia-perl-pe-region @key{RET} @var{code} @key{RET}
567 @findex sepia-perl-pe-region
568 Evaluate @var{code} on each line in the region with @code{$_} bound to
569 the line text, collecting the resulting values of @code{$_}. With a
570 prefix argument, replace the region with the result.
572 @item M-x sepia-perl-ne-region @key{RET} @var{code} @key{RET}
573 @findex sepia-perl-ne-region
574 Evaluate @var{code} as above, but collect the results instead.
576 @item M-x sepia-perlize-region @key{RET} @var{code} @key{RET}
577 @findex sepia-perlize-region
578 Evaluate @var{code} once with @code{$_} bound to the entire region,
579 collecting the final value of @code{$_}. With a prefix argument,
584 @node Scratchpad, , Mutilation, Interactive Perl
587 @findex sepia-scratch
588 Sepia also supports a scratchpad, another form of interaction inspired
589 by Emacs' @code{*scratch*} buffer. To create or switch to the
590 scratchpad, type @kbd{M-x sepia-scratch}. Scratchpad mode is exactly
591 like Sepia mode, except @key{C-j} evaluates the current line and prints
592 the result on the next line.
594 @c ============================================================
595 @node Customization, Internals, Interactive Perl, Top
596 @chapter Customization
598 While Sepia can be customized in both the Perl and Emacs Lisp, most of
599 the user-accessible configuration is in the latter.
606 @node Emacs Variables, Perl Variables, Customization, Customization
607 @section Emacs Variables
609 Since Sepia tries where possible to reuse existing Emacs functionality,
610 its behavior should already be covered by existing customizations. The
611 two variables most likely to need customization are
612 @kbd{sepia-program-name} and @kbd{sepia-perl5lib}. General Sepia mode
613 configuration can be done with @kbd{sepia-mode-hook}, while
614 REPL-specific configuration can be done with @kbd{sepia-repl-mode-hook}.
618 @item sepia-complete-methods
619 If non-@code{nil}, @code{sepia-complete-symbol} will complete
620 simple method calls of the form @code{$x->} or @code{Module->}. Since
621 the former requires evaluation of @code{$x}, this can be disabled.
624 @item sepia-eval-defun-include-decls
625 If non-@code{nil}, attempt to generate a declaration list for
626 @code{sepia-eval-defun}. This is necessary when evaluating some code,
627 such as that calling functions without parentheses, because the presence
628 of declarations affects the parsing of barewords. Default: @code{T}.
630 @item sepia-indent-expand-abbrev
631 If non-@code{nil}, @code{sepia-indent-or-complete} will, if
632 reindentation does not change the current line, expand an abbreviation
633 before point rather than performing completion. Only if no abbreviation
634 is found will it perform completion. Default: @code{T}.
636 @item sepia-module-list-function
637 The function to view a tree of installed modules. Default:
638 @code{w3m-find-file} if Emacs-w3m is installed, or
639 @code{browse-url-of-buffer} otherwise.
641 @item sepia-perldoc-function
642 The function called to view installed modules' documentation. Default:
643 @code{w3m-perldoc} if Emacs-w3m is installed, or @code{cperl-perldoc}
647 A list of directories to include in @code{PERL5LIB} when starting
648 interactive Perl. Default: @code{nil}.
650 @item sepia-prefix-key
651 The prefix to use for for functions in @code{sepia-keymap}. Default:
654 @item sepia-program-name
655 The Perl program name for interactive Perl. Default: ``perl''.
657 @item sepia-use-completion
658 If non-@code{nil}, various Sepia functions will generate completion
659 candidates from interactive Perl when called interactively. This may be
660 slow or undesirable in some situations. Default: @code{T}.
662 @item sepia-view-pod-function
663 The function called to view the current buffer's documentation.
664 Default: @code{sepia-w3m-view-pod} if Emacs-w3m is available, or
665 @code{sepia-perldoc-buffer} otherwise.
669 @node Perl Variables, , Emacs Variables, Customization
670 @section Perl Variables
672 When Sepia starts up, it evaluates the Perl script in @file{~/.sepiarc}.
673 The following variables in the Sepia package control various aspects of
674 interactive evaluation.
679 The package in which user input is evaluated, determined automatically
680 when code is evaluated from a buffer. Default: @code{main}.
683 The function called to format interactive output, normally set with the
684 @code{printer} shortcut.
687 If true, format some values nicely independent of the value of
688 @code{$PRINTER}. Currently, this means columnating lists of simple
689 scalars. Default: true.
692 The trailing end of the prompt string, which should end with ``> ''.
693 Default: @code{"> "}.
696 If true, calls to @code{die} from interactive code will invoke the Sepia
697 debugger. Default: true.
700 If true, calls to @code{warn} from interactive code will invoke the
701 Sepia debugger. Default: false.
704 If true, evaluate interactive expressions in list context. Default: true.
708 Additional REPL shortcuts can be defined with
709 @kbd{Sepia::define_shortcut}. For example
712 Sepia::define_shortcut time => sub @{ print scalar localtime, "\n"; 0 @},
713 'Display the current time.';
716 defines a shortcut ``time'' that displays the current time. For
717 details, see the code in @file{Sepia.pm}.
719 @c ============================================================
720 @node Internals, Credits, Customization, Top
723 Many things remain unexplained except by the code itself, and some
724 details mentioned above should probably be given less prominence. For
725 developer documentation, please see the POD for @code{Sepia} and
726 @code{Sepia::Xref}, and the doc-strings in @file{sepia.el}.
728 @node Credits, Function Index, Internals, Top
733 Found and motivated me to fix a bunch of bugs, created Debian packages.
736 Found and fixed numerous bugs.
739 Portions of the code were lifted from Emacs-w3m, SLIME, ido, and
740 B::Xref, all of which are Free software.
744 @c ============================================================
745 @node Function Index, , Credits, Top
746 @unnumbered Function Index