1 This is sepia.info, produced by makeinfo version 4.8 from sepia.texi.
5 * Sepia: (sepia). Simple Emacs Perl Integration.
9 File: sepia.info, Node: Top, Next: Introduction, Prev: (dir), Up: (dir)
14 Sepia is a set of Perl development tools for Emacs supporting code
15 navigation and interactive evaluation.
28 File: sepia.info, Node: Introduction, Next: Editing, Prev: Top, Up: Top
33 Sepia is a set of tools for Perl development in Emacs. Its goal is to
34 extend CPerl mode to support fast code navigation and interactive
35 development. It is inspired by Emacs' current support for a number of
36 other languages, including Lisp, Python, and Emacs Lisp.
44 File: sepia.info, Node: Getting Started, Next: Philosophy, Prev: Introduction, Up: Introduction
49 To install Sepia, its Emacs Lisp files must be in Emacs' `load-path',
50 and the `lib' directory must be in Perl's `@INC'. Assuming that Sepia
51 has been unpacked in `~/sepia', it can be installed by adding the
52 following lines to `~/.emacs':
54 (add-to-list 'load-path "~/sepia")
55 (setq sepia-perl5lib (list (expand-file-name "~/sepia/lib")))
56 (defalias 'perl-mode 'sepia-mode)
59 Then to bring up the interactive Perl prompt, type `M-x sepia-repl'.
62 File: sepia.info, Node: Philosophy, Prev: Getting Started, Up: Introduction
67 A development environment should support three activities: code
68 spelunking, interaction, and customization. Emacs as an environment for
69 developing Emacs Lisp thoroughly supports all of them: It has commands
70 to visit individual functions' code and documentation, commands to
71 evaluate or step through expressions, and an architecture that
72 encourages customization in Emacs Lisp. As an environment for Perl,
73 however, it is lacking: there is limited interactivity with the Perl
74 debugger, and reasonable documentation browsing, but no support for
75 navigating, editing, and re-evaluating code. Sepia attempts to remedy
78 Modern IDEs also support these three activities, but do so awkwardly.
79 Rather than having functions to visit definitions (`find-function') and
80 search for functions (`apropos'), they clutter the screen with class
81 and file trees. Rather than supporting interactive evaluation of small
82 pieces of code, they perform background semantic checking on whole
83 projects and highlight errors. Rather than allowing minor
84 customizations to grow organically into features, they support limited
85 configuration files and baroque plug-in APIs. Sepia tries to adhere to
86 the apparent Emacs philosophy that rich semantic information should be
87 unobtrusive, and that the best way to build working code is to start by
88 experimenting with small pieces.
90 Language support packages for Emacs vary widely in the degree to
91 which they make use of or replace existing Emacs features. Minimal
92 modes provide keyword-based syntax highlighting and an unadorned comint
93 buffer as an interpreter. Others provide their own specialized
94 equivalents of comint, eldoc, completion, and other Emacs features.
95 Sepia takes a third approach by trying to do as much as possible with
96 existing Emacs features, even when they are not optimal for Perl. For
97 example, it uses comint to communicate with the subprocess, eldoc to
98 display documentation, and grep to list source locations.
100 This approach has three advantages: First, it maximizes the number of
101 features that can be supported with limited development time. Second,
102 it respects users' settings. A seasoned Emacs user may have changed
103 hundreds of settings, so a mode that reimplements features will have to
104 support equivalent settings, and will force the user to re-specify them.
105 Finally, this approach respects decades of development spent, as Neal
106 Stephenson put it, "focused with maniacal intensity on the deceptively
107 simple-seeming problem of editing text." Many non-obvious choices go
108 into making a polished interface, and while a reimplementation gets rid
109 of accumulated cruft, it must rediscover these hidden trade-offs.
111 Anyways, I hope you enjoy using Sepia. Its development style is
112 strange for someone used Perl's typical mix of one-liners and
113 edit-save-run, but once you are accustomed to it, you may find it very
117 File: sepia.info, Node: Editing, Next: Interactive Perl, Prev: Introduction, Up: Top
122 Sepia's first contribution is a set of commands to explore a Perl
123 codebase. These include commands to browse and display documentation,
124 to find function definitions, and to query a cross-reference database of
125 function and variable uses. Sepia also provides intelligent symbol
135 File: sepia.info, Node: Completion, Next: Navigation, Prev: Editing, Up: Editing
140 Sepia implements partial-word completion that communicates with the
141 inferior Perl process. For example, `%S:X:v_u' completes to
142 `%Sepia::Xref::var_use' when Sepia is loaded. This completion only
143 operates on functions and global variables known to the Perl
144 interpreter, so it works best when code and interpreter are in sync.
146 More precisely, completion examines the text before point and tries
147 each of the following in turn, using the first successful approach:
149 1. If the text looks like a method call (e.g. `$object->f' or
150 `Class->f'), complete on methods.
152 2. If it looks like a variable (e.g. `%hash' or `$scalar'), complete
155 3. Complete on modules and functions.
157 4. Otherwise, complete on Perl built-in operators.
159 For each of the first three cases, completions candidates are first
160 generated by splitting the text on characters `[:_]' and matching the
161 resulting word parts. For example, `X:a_b' will complete to all
162 symbols matching `^X[^:]*:+a[^:_]*_b' such as `Xref::a_bug' and
163 `X::always_bites_me'. If no matches result, the text is treated as an
164 acronym. For example, `dry' will complete to `dont_repeat_yourself'.
166 Completion is performed by the following commands:
167 `M-x sepia-complete-symbol'
168 Complete the symbol before point as described above. Note that
169 this does not consider lexical scope, and is always case-sensitive,
170 independent of `completion-ignore-case'.
173 `M-x sepia-indent-or-complete'
174 First try to reindent the current line. If its indentation does
175 not change, then try to expand an abbrev at point (unless
176 `sepia-indent-expand-abbrev' is `nil'). If no abbrev is expanded,
177 then call `sepia-complete-symbol'.
181 File: sepia.info, Node: Navigation, Next: Documentation, Prev: Completion, Up: Editing
186 Sepia provides several commands for navigating program source. All of
187 them rely on information from the inferior Perl process, so it is
188 important both that it be running, and that its internal representation
189 of the program match the program source. The commands marked (Xref)
190 below also rely on a cross-reference database, which must be explicitly
191 rebuilt by calling `xref-rebuild' when the program changes.
193 There are two basic kinds of navigation commands. The first kind
194 jumps directly to the first matching location when possible, prompting
195 only if no such location is found. These commands find only a single
200 Guess what kind of identifier is at point, and try to do the right
201 thing: for a function, find its definition(s); for a variable,
202 find its uses; for a module, view its documentation; otherwise,
203 prompt for the name of a function to visit. `sepia-dwim'
204 automatically goes to the first function definition or variable
209 Jump directly to the definition of the function at point,
210 prompting if point is not on a known function. If multiple
211 definitions are found, choose one arbitrarily. This function is
212 similar to `sepia-defs', and the two should probably be merged.
215 `M-x sepia-jump-to-symbol'
216 Navigate to a function using "ido" interactive completion. Within
217 interactive completion, press <:> to descend into a package, <DEL>
218 to ascend to a parent package, and <RET> to go to the
219 currently-selected function.
222 The second kind of navigation commands always prompts the user -
223 though usually with a sensible default value - and finds multiple
224 locations. When called with a prefix argument, these commands present
225 their results in a `grep-mode' buffer. When called _without_ a prefix
226 argument, they place all results on the found-location ring and jump
227 directly to the first. The remaining locations can be cycled through by
228 calls to `sepia-next'.
232 Find definition(s) of function NAME.
235 `M-x sepia-module-find NAME <RET>'
236 Find the source of module NAME.
239 `M-x sepia-apropos REGEXP <RET>'
240 Find definitions of all functions whose names match REGEXP.
243 `M-x sepia-callers NAME <RET>'
244 (Xref) Find calls to function NAME.
247 `M-x sepia-callees NAME <RET>'
248 (Xref) Find the definitions of functions called by NAME.
251 `M-x sepia-var-uses NAME <RET>'
252 (Xref) Find uses of the global variable NAME.
255 `M-x sepia-var-defs NAME <RET>'
256 (Xref) Find definitions of global variable NAME. Since Perl's
257 global variables are not declared, this is rarely useful
260 Finally, there are several other navigation-related commands that do
261 not fit into either of the above categories.
265 Cycle through the definitions found by the previous <M-.> search.
269 Rebuild the cross-reference database by walking the op-tree and
274 Execute the `find-tag' command typically bound to <M-.>.
278 File: sepia.info, Node: Documentation, Prev: Navigation, Up: Editing
283 Sepia can be used to browse installed modules' documentation, to format
284 and display the current buffer's POD, and to browse the list of modules
285 installed on the system.
288 `M-x sepia-perldoc-this'
289 View documentation for module NAME or Perl manual page NAME.
293 Format and view the current buffer's documentation.
296 Browse a tree of installed packages. This lists only the top-level
297 packages from installed distributions, so if package `My::Stuff'
298 also provides `My::Stuff::Details', it will not be displayed. When
299 Emacs-w3m is available, each module is linked to its documentation.
302 Browse a tree of both top-level and internal packages, like
303 `sepia-package-list'.
306 Sepia also integrates with eldoc (at least in GNU Emacs >= 22).
307 Documentation for Perl operators and control structures is taken from
308 CPerl mode. Sepia will also display documentation for user-defined
309 functions if their POD is formatted in the standard way, with functions
310 described in a "=head2" or "=item" entry. To load user documentation,
311 visit the relevant file and type `M-x sepia-doc-update'.
313 If `Module::CoreList' is available, Sepia's eldoc function will also
314 display the first version of Perl with which a module was shipped.
315 This is intended to give the programmer a sense of when he is creating
316 external dependencies.
319 File: sepia.info, Node: Interactive Perl, Next: Customization, Prev: Editing, Up: Top
324 Sepia's second main contribution is an interactive interface (REPL) to
325 an inferior Perl process. The interface is based on GUD mode, and
326 inherits many of its bindings; this chapter discusses only the Sepia
327 extensions. To start or switch to the repl, type `M-x sepia-repl'. As
328 in Sepia mode, <TAB> in the REPL performs partial-word completion with
329 `sepia-complete-symbol'.
331 Sepia also provides a number of other ways to evaluate pieces of
332 code in Perl, and commands to process buffer text using the inferior
344 File: sepia.info, Node: Shortcuts, Next: Debugger, Prev: Interactive Perl, Up: Interactive Perl
349 "Shortcuts" are commands handled specially by the REPL rather than
350 being evaluated as Perl code. They either communicate with the REPL
351 function, or provide a convenient interface to variables in the Sepia
352 package. Shortcuts are prefixed by a comma (<,>), and may be
353 abbreviated to the shortest unique prefix.
356 Change Perl's current directory to DIR.
359 Turn Sepia debugger hook on or off, or toggle if VAL is missing.
361 `define NAME ['DOC'] BODY...'
362 Define NAME as a shortcut for Perl code BODY, with optional
363 documentation DOC, surrounded by single quotes. BODY is passed
364 the raw command-line text as its first argument.
367 Delete the current breakpoint.
370 Set the output format to TYPE, either "dumper" (using
371 `Data::Dumper'), "dump" (`Data::Dump'), "yaml" (`YAML'), or
372 "plain" (stringification). Default: "dumper".
375 Display a list of shortcuts.
380 `methods NAME [REGEXP]'
381 Display a list of functions defined in package NAME and its
382 `ISA'-ancestors matching optional pattern REGEXP.
385 Set the default evaluation package to NAME.
388 Show the process's current working directory.
391 Exit the inferior Perl process.
394 Reload `Sepia.pm' and recursively invoke the REPL. This command is
395 mostly of interest when working on Sepia itself.
398 Execute shell command COMMAND, displaying its standard output and
402 Set evaluation strictness to VAL, or toggle it if VAL is not
403 given. Note that turning strictness off and on clears the REPL's
407 Undefine shortcut NAME. *Warning*: this can equally be used to
408 remove built-in shortcuts.
411 Set the evaluation context to VAL, or toggle between scalar and
414 `who PACKAGE [REGEXP]'
416 List identifiers in PACKAGE (main by default) matching optional
421 File: sepia.info, Node: Debugger, Next: Evaluation, Prev: Shortcuts, Up: Interactive Perl
426 Sepia uses Perl's debugger hooks and GUD mode to support conditional
427 breakpoints and single-stepping, and overrides Perl's `die()' to invoke
428 the debugger rather than unwind the stack. This makes it possible to
429 produce a backtrace, inspect and modify global variables, and even
430 continue execution when a program tries to kill itself. If the
431 PadWalker module is available, Sepia also provides functions to inspect
432 and modify lexical variables.
434 The debugger has its own set of shortcuts, also prefixed by a comma.
439 `break FILE:LINE [EXPR]'
440 Set a breakpoint in FILE at LINE. If EXPR is supplied, stop only
441 if it evaluates to true.
445 Move the current stack frame up or down by N (or one) frames.
448 Inspect lexicals in the current frame or frame N, counting upward
455 Advance N (or one) lines, skipping subroutine calls.
460 Continue as the program would have executed without debugger
461 intervention, dying if the debugger was called from `die()'.
464 Continue execution as if `die()' had returned the value of EXPR,
465 which is evaluated in the global environment.
468 Step forward N (or one) lines, descending into subroutines.
472 File: sepia.info, Node: Evaluation, Next: Mutilation, Prev: Debugger, Up: Interactive Perl
477 When interactive Perl is running, Sepia can evaluate regions of code in
478 the inferior Perl process. The following commands assume that this
479 process has already been started by calling `sepia-repl'.
482 `M-x sepia-eval-defun'
483 Evaluate the function around point in the inferior Perl process.
484 If it contains errors, jump to the location of the first.
487 `M-x sepia-load-file'
488 Save the current buffer, then reload its file and if warnings or
489 errors occur, display an error buffer. With a prefix argument,
490 also rebuild the cross-reference index.
493 `M-x sepia-eval-expression <RET> EXPR <RET>'
494 Evaluate EXPR in scalar context and echo the result. With a
495 prefix argument, evaluate in list context.
499 Set the REPL's working directory to the current buffer's directory.
503 File: sepia.info, Node: Mutilation, Next: Scratchpad, Prev: Evaluation, Up: Interactive Perl
508 Sepia contains several functions to operate on regions of text using the
509 interactive Perl process. These functions can be used like standard
510 one-liners (e.g. `perl -pe ...'), with the advantage that all of the
511 functions and variables in the interactive session are available.
513 `M-x sepia-perl-pe-region <RET> CODE <RET>'
514 Evaluate CODE on each line in the region with `$_' bound to the
515 line text, collecting the resulting values of `$_'. With a prefix
516 argument, replace the region with the result.
518 `M-x sepia-perl-ne-region <RET> CODE <RET>'
519 Evaluate CODE as above, but collect the results instead.
521 `M-x sepia-perlize-region <RET> CODE <RET>'
522 Evaluate CODE once with `$_' bound to the entire region,
523 collecting the final value of `$_'. With a prefix argument,
528 File: sepia.info, Node: Scratchpad, Prev: Mutilation, Up: Interactive Perl
533 Sepia also supports a scratchpad, another form of interaction inspired
534 by Emacs' `*scratch*' buffer. To create or switch to the scratchpad,
535 type `M-x sepia-scratch'. Scratchpad mode is exactly like Sepia mode,
536 except <C-j> evaluates the current line and prints the result on the
540 File: sepia.info, Node: Customization, Next: Internals, Prev: Interactive Perl, Up: Top
545 While Sepia can be customized in both the Perl and Emacs Lisp, most of
546 the user-accessible configuration is in the latter.
554 File: sepia.info, Node: Emacs Variables, Next: Perl Variables, Prev: Customization, Up: Customization
559 Since Sepia tries where possible to reuse existing Emacs functionality,
560 its behavior should already be covered by existing customizations. The
561 two variables most likely to need customization are
562 `sepia-program-name' and `sepia-perl5lib'. General Sepia mode
563 configuration can be done with `sepia-mode-hook', while REPL-specific
564 configuration can be done with `sepia-repl-mode-hook'.
566 `sepia-complete-methods'
567 If non-`nil', `sepia-complete-symbol' will complete simple method
568 calls of the form `$x->' or `Module->'. Since the former requires
569 evaluation of `$x', this can be disabled. Default: `T'.
571 `sepia-eval-defun-include-decls'
572 If non-`nil', attempt to generate a declaration list for
573 `sepia-eval-defun'. This is necessary when evaluating some code,
574 such as that calling functions without parentheses, because the
575 presence of declarations affects the parsing of barewords.
578 `sepia-indent-expand-abbrev'
579 If non-`nil', `sepia-indent-or-complete' will, if reindentation
580 does not change the current line, expand an abbreviation before
581 point rather than performing completion. Only if no abbreviation
582 is found will it perform completion. Default: `T'.
584 `sepia-module-list-function'
585 The function to view a tree of installed modules. Default:
586 `w3m-find-file' if Emacs-w3m is installed, or
587 `browse-url-of-buffer' otherwise.
589 `sepia-perldoc-function'
590 The function called to view installed modules' documentation.
591 Default: `w3m-perldoc' if Emacs-w3m is installed, or
592 `cperl-perldoc' otherwise.
595 A list of directories to include in `PERL5LIB' when starting
596 interactive Perl. Default: `nil'.
599 The prefix to use for for functions in `sepia-keymap'. Default:
603 The Perl program name for interactive Perl. Default: "perl".
605 `sepia-use-completion'
606 If non-`nil', various Sepia functions will generate completion
607 candidates from interactive Perl when called interactively. This
608 may be slow or undesirable in some situations. Default: `T'.
610 `sepia-view-pod-function'
611 The function called to view the current buffer's documentation.
612 Default: `sepia-w3m-view-pod' if Emacs-w3m is available, or
613 `sepia-perldoc-buffer' otherwise.
617 File: sepia.info, Node: Perl Variables, Prev: Emacs Variables, Up: Customization
622 When Sepia starts up, it evaluates the Perl script in `~/.sepiarc'.
623 The following variables in the Sepia package control various aspects of
624 interactive evaluation.
627 The package in which user input is evaluated, determined
628 automatically when code is evaluated from a buffer. Default:
632 The function called to format interactive output, normally set
633 with the `printer' shortcut.
636 If true, format some values nicely independent of the value of
637 `$PRINTER'. Currently, this means columnating lists of simple
638 scalars. Default: true.
641 The trailing end of the prompt string, which should end with "> ".
645 If true, calls to `die' from interactive code will invoke the Sepia
646 debugger. Default: true.
649 If true, calls to `warn' from interactive code will invoke the
650 Sepia debugger. Default: false.
653 If true, evaluate interactive expressions in list context.
657 Additional REPL shortcuts can be defined with
658 `Sepia::define_shortcut'. For example
660 Sepia::define_shortcut time => sub { print scalar localtime, "\n"; 0 },
661 'Display the current time.';
663 defines a shortcut "time" that displays the current time. For
664 details, see the code in `Sepia.pm'.
667 File: sepia.info, Node: Internals, Next: Credits, Prev: Customization, Up: Top
672 Many things remain unexplained except by the code itself, and some
673 details mentioned above should probably be given less prominence. For
674 developer documentation, please see the POD for `Sepia' and
675 `Sepia::Xref', and the doc-strings in `sepia.el'.
678 File: sepia.info, Node: Credits, Next: Function Index, Prev: Internals, Up: Top
684 Found and motivated me to fix a bunch of bugs, created Debian
688 Found and fixed numerous bugs.
691 Portions of the code were lifted from Emacs-w3m, SLIME, ido, and
692 B::Xref, all of which are Free software.
696 File: sepia.info, Node: Function Index, Prev: Credits, Up: Top
704 * sepia-apropos: Navigation. (line 60)
705 * sepia-callees: Navigation. (line 68)
706 * sepia-callers: Navigation. (line 64)
707 * sepia-complete-symbol: Completion. (line 34)
708 * sepia-defs: Navigation. (line 52)
709 * sepia-dwim: Navigation. (line 20)
710 * sepia-eval-defun: Evaluation. (line 12)
711 * sepia-eval-expression: Evaluation. (line 23)
712 * sepia-indent-or-complete: Completion. (line 40)
713 * sepia-install-eldoc: Documentation. (line 29)
714 * sepia-jump-to-symbol: Navigation. (line 36)
715 * sepia-load-file: Evaluation. (line 17)
716 * sepia-location: Navigation. (line 29)
717 * sepia-mode: Editing. (line 6)
718 * sepia-module-find: Navigation. (line 56)
719 * sepia-module-list: Documentation. (line 25)
720 * sepia-next: Navigation. (line 85)
721 * sepia-package-list: Documentation. (line 19)
722 * sepia-perl-ne-region: Mutilation. (line 17)
723 * sepia-perl-pe-region: Mutilation. (line 12)
724 * sepia-perldoc-this: Documentation. (line 12)
725 * sepia-perlize-region: Mutilation. (line 20)
726 * sepia-rebuild: Navigation. (line 89)
727 * sepia-repl: Interactive Perl. (line 6)
728 * sepia-scratch: Scratchpad. (line 6)
729 * sepia-var-defs: Navigation. (line 76)
730 * sepia-var-uses: Navigation. (line 72)
731 * sepia-view-pod: Documentation. (line 16)
737 Node: Introduction
\x7f512
738 Node: Getting Started
\x7f933
739 Node: Philosophy
\x7f1558
740 Node: Editing
\x7f4564
741 Node: Completion
\x7f5026
742 Node: Navigation
\x7f6870
743 Node: Documentation
\x7f10219
744 Node: Interactive Perl
\x7f11766
745 Node: Shortcuts
\x7f12503
746 Node: Debugger
\x7f14704
747 Node: Evaluation
\x7f16163
748 Node: Mutilation
\x7f17139
749 Node: Scratchpad
\x7f18091
750 Node: Customization
\x7f18496
751 Node: Emacs Variables
\x7f18797
752 Node: Perl Variables
\x7f21292
753 Node: Internals
\x7f22779
754 Node: Credits
\x7f23139
755 Node: Function Index
\x7f23518