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.
29 File: sepia.info, Node: Introduction, Next: Editing, Prev: Top, Up: Top
34 Sepia is a set of tools for Perl development in Emacs. Its goal is to
35 extend CPerl mode to support fast code navigation and interactive
36 development. It is inspired by Emacs' current support for a number of
37 other languages, including Lisp, Python, and Emacs Lisp.
45 File: sepia.info, Node: Getting Started, Next: Philosophy, Prev: Introduction, Up: Introduction
50 To install Sepia, its Emacs Lisp files must be in Emacs' `load-path',
51 and the `lib' directory must be in Perl's `@INC'. Assuming that Sepia
52 has been unpacked in `~/sepia', it can be installed by adding the
53 following lines to `~/.emacs':
55 (add-to-list 'load-path "~/sepia")
56 (setq sepia-perl5lib (list (expand-file-name "~/sepia/lib")))
57 (defalias 'perl-mode 'sepia-mode)
60 Then to bring up the interactive Perl prompt, type `M-x sepia-repl'.
63 File: sepia.info, Node: Philosophy, Prev: Getting Started, Up: Introduction
68 A development environment should support three activities: code
69 spelunking, interaction, and customization. Emacs as an environment for
70 developing Emacs Lisp thoroughly supports all of them: It has commands
71 to visit individual functions' code and documentation, commands to
72 evaluate or step through expressions, and an architecture that
73 encourages customization in Emacs Lisp. As an environment for Perl,
74 however, it is lacking: there is limited interactivity with the Perl
75 debugger, and reasonable documentation browsing, but no support for
76 navigating, editing, and re-evaluating code. Sepia attempts to remedy
79 Modern IDEs also support these three activities, but do so awkwardly.
80 Rather than having functions to visit definitions (`find-function') and
81 search for functions (`apropos'), they clutter the screen with class
82 and file trees. Rather than supporting interactive evaluation of small
83 pieces of code, they perform background semantic checking on whole
84 projects and highlight errors. Rather than allowing minor
85 customizations to grow organically into features, they support limited
86 configuration files and baroque plug-in APIs. Sepia tries to adhere to
87 the apparent Emacs philosophy that rich semantic information should be
88 unobtrusive, and that the best way to build working code is to start by
89 experimenting with small pieces.
91 Language support packages for Emacs vary widely in the degree to
92 which they make use of or replace existing Emacs features. Minimal
93 modes provide keyword-based syntax highlighting and an unadorned comint
94 buffer as an interpreter. Others provide their own specialized
95 equivalents of comint, eldoc, completion, and other Emacs features.
96 Sepia takes a third approach by trying to do as much as possible with
97 existing Emacs features, even when they are not optimal for Perl. For
98 example, it uses comint to communicate with the subprocess, eldoc to
99 display documentation, and grep to list source locations.
101 This approach has three advantages: First, it maximizes the number of
102 features that can be supported with limited development time. Second,
103 it respects users' settings. A seasoned Emacs user may have changed
104 hundreds of settings, so a mode that reimplements features will have to
105 support equivalent settings, and will force the user to re-specify them.
106 Finally, this approach respects decades of development spent, as Neal
107 Stephenson put it, "focused with maniacal intensity on the deceptively
108 simple-seeming problem of editing text." Many non-obvious choices go
109 into making a polished interface, and while a reimplementation gets rid
110 of accumulated cruft, it must rediscover these hidden trade-offs.
112 Anyways, I hope you enjoy using Sepia. Its development style is
113 strange for someone used Perl's typical mix of one-liners and
114 edit-save-run, but once you are accustomed to it, you may find it very
118 File: sepia.info, Node: Editing, Next: Interactive Perl, Prev: Introduction, Up: Top
123 Sepia's first contribution is a set of commands to explore a Perl
124 codebase. These include commands to browse and display documentation,
125 to find function definitions, and to query a cross-reference database of
126 function and variable uses. Sepia also provides intelligent symbol
136 File: sepia.info, Node: Completion, Next: Navigation, Prev: Editing, Up: Editing
141 Sepia implements partial-word completion that communicates with the
142 inferior Perl process. For example, `%S:X:v_u' completes to
143 `%Sepia::Xref::var_use' when Sepia is loaded. This completion only
144 operates on functions and global variables known to the Perl
145 interpreter, so it works best when code and interpreter are in sync.
147 More precisely, completion examines the text before point and tries
148 each of the following in turn, using the first successful approach:
150 1. If the text looks like a method call (e.g. `$object->f' or
151 `Class->f'), complete on methods.
153 2. If it looks like a variable (e.g. `%hash' or `$scalar'), complete
156 3. Complete on modules and functions.
158 4. Otherwise, complete on Perl built-in operators.
160 For each of the first three cases, completions candidates are first
161 generated by splitting the text on characters `[:_]' and matching the
162 resulting word parts. For example, `X:a_b' will complete to all
163 symbols matching `^X[^:]*:+a[^:_]*_b' such as `Xref::a_bug' and
164 `X::always_bites_me'. If no matches result, the text is treated as an
165 acronym. For example, `dry' will complete to `dont_repeat_yourself'.
167 Completion is performed by the following commands:
168 `M-x sepia-complete-symbol'
169 Complete the symbol before point as described above. Note that
170 this does not consider lexical scope, and is always case-sensitive,
171 independent of `completion-ignore-case'.
174 `M-x sepia-indent-or-complete'
175 First try to reindent the current line. If its indentation does
176 not change, then try to expand an abbrev at point (unless
177 `sepia-indent-expand-abbrev' is `nil'). If no abbrev is expanded,
178 then call `sepia-complete-symbol'.
182 File: sepia.info, Node: Navigation, Next: Documentation, Prev: Completion, Up: Editing
187 Sepia provides several commands for navigating program source. All of
188 them rely on information from the inferior Perl process, so it is
189 important both that it be running, and that its internal representation
190 of the program match the program source. The commands marked (Xref)
191 below also rely on a cross-reference database, which must be explicitly
192 rebuilt by calling `xref-rebuild' when the program changes.
194 There are two basic kinds of navigation commands. The first kind
195 jumps directly to the first matching location when possible, prompting
196 only if no such location is found. These commands find only a single
201 Guess what kind of identifier is at point, and try to do the right
202 thing: for a function, find its definition(s); for a variable,
203 find its uses; for a module, view its documentation; otherwise,
204 prompt for the name of a function to visit. `sepia-dwim'
205 automatically goes to the first function definition or variable
210 Jump directly to the definition of the function at point,
211 prompting if point is not on a known function. If multiple
212 definitions are found, choose one arbitrarily. This function is
213 similar to `sepia-defs', and the two should probably be merged.
216 `M-x sepia-jump-to-symbol'
217 Navigate to a function using "ido" interactive completion. Within
218 interactive completion, press <:> to descend into a package, <DEL>
219 to ascend to a parent package, and <RET> to go to the
220 currently-selected function.
223 The second kind of navigation commands always prompts the user -
224 though usually with a sensible default value - and finds multiple
225 locations. When called with a prefix argument, these commands present
226 their results in a `grep-mode' buffer. When called _without_ a prefix
227 argument, they place all results on the found-location ring and jump
228 directly to the first. The remaining locations can be cycled through by
229 calls to `sepia-next'.
233 Find definition(s) of function NAME.
236 `M-x sepia-module-find NAME <RET>'
237 Find the source of module NAME.
240 `M-x sepia-apropos REGEXP <RET>'
241 Find definitions of all functions whose names match REGEXP.
244 `M-x sepia-callers NAME <RET>'
245 (Xref) Find calls to function NAME.
248 `M-x sepia-callees NAME <RET>'
249 (Xref) Find the definitions of functions called by NAME.
252 `M-x sepia-var-uses NAME <RET>'
253 (Xref) Find uses of the global variable NAME.
256 `M-x sepia-var-defs NAME <RET>'
257 (Xref) Find definitions of global variable NAME. Since Perl's
258 global variables are not declared, this is rarely useful
261 Finally, there are several other navigation-related commands that do
262 not fit into either of the above categories.
266 Cycle through the definitions found by the previous <M-.> search.
270 Rebuild the cross-reference database by walking the op-tree and
275 Execute the `find-tag' command typically bound to <M-.>.
279 File: sepia.info, Node: Documentation, Prev: Navigation, Up: Editing
284 Sepia can be used to browse installed modules' documentation, to format
285 and display the current buffer's POD, and to browse the list of modules
286 installed on the system.
289 `M-x sepia-perldoc-this'
290 View documentation for module NAME or Perl manual page NAME.
294 Format and view the current buffer's documentation.
297 Browse a tree of installed packages. This lists only the top-level
298 packages from installed distributions, so if package `My::Stuff'
299 also provides `My::Stuff::Details', it will not be displayed. When
300 Emacs-w3m is available, each module is linked to its documentation.
303 Browse a tree of both top-level and internal packages, like
304 `sepia-package-list'.
307 Sepia also integrates with eldoc (at least in GNU Emacs >= 22).
308 Documentation for Perl operators and control structures is taken from
309 CPerl mode. Sepia will also display documentation for user-defined
310 functions if their POD is formatted in the standard way, with functions
311 described in a "=head2" or "=item" entry. To load user documentation,
312 visit the relevant file and type `M-x sepia-doc-update'.
314 If `Module::CoreList' is available, Sepia's eldoc function will also
315 display the first version of Perl with which a module was shipped.
316 This is intended to give the programmer a sense of when he is creating
317 external dependencies.
320 File: sepia.info, Node: Interactive Perl, Next: CPAN browsing, Prev: Editing, Up: Top
325 Sepia's second main contribution is an interactive interface (REPL) to
326 an inferior Perl process. The interface is based on GUD mode, and
327 inherits many of its bindings; this chapter discusses only the Sepia
328 extensions. To start or switch to the repl, type `M-x sepia-repl'. As
329 in Sepia mode, <TAB> in the REPL performs partial-word completion with
330 `sepia-complete-symbol'.
332 Sepia also provides a number of other ways to evaluate pieces of
333 code in Perl, and commands to process buffer text using the inferior
345 File: sepia.info, Node: Shortcuts, Next: Debugger, Prev: Interactive Perl, Up: Interactive Perl
350 "Shortcuts" are commands handled specially by the REPL rather than
351 being evaluated as Perl code. They either communicate with the REPL
352 function, or provide a convenient interface to variables in the Sepia
353 package. Shortcuts are prefixed by a comma (<,>), and may be
354 abbreviated to the shortest unique prefix.
357 Change Perl's current directory to DIR.
360 Turn Sepia debugger hook on or off, or toggle if VAL is missing.
362 `define NAME ['DOC'] BODY...'
363 Define NAME as a shortcut for Perl code BODY, with optional
364 documentation DOC, surrounded by single quotes. BODY is passed
365 the raw command-line text as its first argument.
368 Delete the current breakpoint.
371 Set the output format to TYPE, either "dumper" (using
372 `Data::Dumper'), "dump" (`Data::Dump'), "yaml" (`YAML'), or
373 "plain" (stringification). Default: "dumper".
376 Display a list of shortcuts.
381 `methods NAME [REGEXP]'
382 Display a list of functions defined in package NAME and its
383 `ISA'-ancestors matching optional pattern REGEXP.
386 Set the default evaluation package to NAME.
389 Show the process's current working directory.
392 Exit the inferior Perl process.
395 Reload `Sepia.pm' and recursively invoke the REPL. This command is
396 mostly of interest when working on Sepia itself.
399 Execute shell command COMMAND, displaying its standard output and
403 Set evaluation strictness to VAL, or toggle it if VAL is not
404 given. Note that turning strictness off and on clears the REPL's
408 Undefine shortcut NAME. *Warning*: this can equally be used to
409 remove built-in shortcuts.
412 Set the evaluation context to VAL, or toggle between scalar and
415 `who PACKAGE [REGEXP]'
417 List identifiers in PACKAGE (main by default) matching optional
422 File: sepia.info, Node: Debugger, Next: Evaluation, Prev: Shortcuts, Up: Interactive Perl
427 Sepia uses Perl's debugger hooks and GUD mode to support conditional
428 breakpoints and single-stepping, and overrides Perl's `die()' to invoke
429 the debugger rather than unwind the stack. This makes it possible to
430 produce a backtrace, inspect and modify global variables, and even
431 continue execution when a program tries to kill itself. If the
432 PadWalker module is available, Sepia also provides functions to inspect
433 and modify lexical variables.
435 The debugger has its own set of shortcuts, also prefixed by a comma.
440 `break FILE:LINE [EXPR]'
441 Set a breakpoint in FILE at LINE. If EXPR is supplied, stop only
442 if it evaluates to true.
446 Move the current stack frame up or down by N (or one) frames.
449 Inspect lexicals in the current frame or frame N, counting upward
456 Advance N (or one) lines, skipping subroutine calls.
461 Continue as the program would have executed without debugger
462 intervention, dying if the debugger was called from `die()'.
465 Continue execution as if `die()' had returned the value of EXPR,
466 which is evaluated in the global environment.
469 Step forward N (or one) lines, descending into subroutines.
472 Return EXPR from the innermost call to SUB. This is a somewhat
473 dangerous and experimental feature, but is probably more useful
474 than returning a value from `die()'.
478 File: sepia.info, Node: Evaluation, Next: Mutilation, Prev: Debugger, Up: Interactive Perl
483 When interactive Perl is running, Sepia can evaluate regions of code in
484 the inferior Perl process. The following commands assume that this
485 process has already been started by calling `sepia-repl'.
488 `M-x sepia-eval-defun'
489 Evaluate the function around point in the inferior Perl process.
490 If it contains errors, jump to the location of the first.
493 `M-x sepia-load-file'
494 Save the current buffer, then reload its file and if warnings or
495 errors occur, display an error buffer. With a prefix argument,
496 also rebuild the cross-reference index.
499 `M-x sepia-eval-expression <RET> EXPR <RET>'
500 Evaluate EXPR in scalar context and echo the result. With a
501 prefix argument, evaluate in list context.
505 Set the REPL's working directory to the current buffer's directory.
509 File: sepia.info, Node: Mutilation, Next: Scratchpad, Prev: Evaluation, Up: Interactive Perl
514 Sepia contains several functions to operate on regions of text using the
515 interactive Perl process. These functions can be used like standard
516 one-liners (e.g. `perl -pe ...'), with the advantage that all of the
517 functions and variables in the interactive session are available.
519 `M-x sepia-perl-pe-region <RET> CODE <RET>'
520 Evaluate CODE on each line in the region with `$_' bound to the
521 line text, collecting the resulting values of `$_'. With a prefix
522 argument, replace the region with the result.
524 `M-x sepia-perl-ne-region <RET> CODE <RET>'
525 Evaluate CODE as above, but collect the results instead.
527 `M-x sepia-perlize-region <RET> CODE <RET>'
528 Evaluate CODE once with `$_' bound to the entire region,
529 collecting the final value of `$_'. With a prefix argument,
534 File: sepia.info, Node: Scratchpad, Prev: Mutilation, Up: Interactive Perl
539 Sepia also supports a scratchpad, another form of interaction inspired
540 by Emacs' `*scratch*' buffer. To create or switch to the scratchpad,
541 type `M-x sepia-scratch'. Scratchpad mode is exactly like Sepia mode,
542 except <C-j> evaluates the current line and prints the result on the
546 File: sepia.info, Node: CPAN browsing, Next: Customization, Prev: Interactive Perl, Up: Top
551 Sepia has rudimentary support for browsing documentation and installing
552 modules from CPAN. To list modules with names matching a pattern, call
553 `sepia-cpan-search'. In the `*sepia-cpan*' buffer, the pressing the
554 single keys listed below on the module-name buttons will perform the
555 corresponding action on the named module.
558 `M-x sepia-cpan-search <RET> PATTERN <RET>'
559 List modules whose names match PATTERN.
562 `M-x sepia-cpan-readme <RET> MODULE <RET>'
563 Fetch and display MODULE's README file.
566 `M-x sepia-cpan-doc <RET> MODULE <RET>'
567 Browse MODULE's documentation on `http://search.cpan.org'.
570 `M-x sepia-cpan-install <RET> MODULE <RET>'
571 Install MODULE and its prerequisites. This feature is not yet
576 File: sepia.info, Node: Customization, Next: Internals, Prev: CPAN browsing, Up: Top
581 While Sepia can be customized in both the Perl and Emacs Lisp, most of
582 the user-accessible configuration is in the latter.
590 File: sepia.info, Node: Emacs Variables, Next: Perl Variables, Prev: Customization, Up: Customization
595 Since Sepia tries where possible to reuse existing Emacs functionality,
596 its behavior should already be covered by existing customizations. The
597 two variables most likely to need customization are
598 `sepia-program-name' and `sepia-perl5lib'. General Sepia mode
599 configuration can be done with `sepia-mode-hook', while REPL-specific
600 configuration can be done with `sepia-repl-mode-hook'.
602 `sepia-complete-methods'
603 If non-`nil', `sepia-complete-symbol' will complete simple method
604 calls of the form `$x->' or `Module->'. Since the former requires
605 evaluation of `$x', this can be disabled. Default: `T'.
607 `sepia-eval-defun-include-decls'
608 If non-`nil', attempt to generate a declaration list for
609 `sepia-eval-defun'. This is necessary when evaluating some code,
610 such as that calling functions without parentheses, because the
611 presence of declarations affects the parsing of barewords.
614 `sepia-indent-expand-abbrev'
615 If non-`nil', `sepia-indent-or-complete' will, if reindentation
616 does not change the current line, expand an abbreviation before
617 point rather than performing completion. Only if no abbreviation
618 is found will it perform completion. Default: `T'.
620 `sepia-module-list-function'
621 The function to view a tree of installed modules. Default:
622 `w3m-find-file' if Emacs-w3m is installed, or
623 `browse-url-of-buffer' otherwise.
625 `sepia-perldoc-function'
626 The function called to view installed modules' documentation.
627 Default: `w3m-perldoc' if Emacs-w3m is installed, or
628 `cperl-perldoc' otherwise.
631 A list of directories to include in `PERL5LIB' when starting
632 interactive Perl. Default: `nil'.
635 The prefix to use for for functions in `sepia-keymap'. Default:
639 The Perl program name for interactive Perl. Default: "perl".
641 `sepia-use-completion'
642 If non-`nil', various Sepia functions will generate completion
643 candidates from interactive Perl when called interactively. This
644 may be slow or undesirable in some situations. Default: `T'.
646 `sepia-view-pod-function'
647 The function called to view the current buffer's documentation.
648 Default: `sepia-w3m-view-pod' if Emacs-w3m is available, or
649 `sepia-perldoc-buffer' otherwise.
653 File: sepia.info, Node: Perl Variables, Prev: Emacs Variables, Up: Customization
658 When Sepia starts up, it evaluates the Perl script in `~/.sepiarc'.
659 The following variables in the Sepia package control various aspects of
660 interactive evaluation.
663 The package in which user input is evaluated, determined
664 automatically when code is evaluated from a buffer. Default:
668 The function called to format interactive output, normally set
669 with the `printer' shortcut.
672 If true, format some values nicely independent of the value of
673 `$PRINTER'. Currently, this means columnating lists of simple
674 scalars. Default: true.
677 The trailing end of the prompt string, which should end with "> ".
681 If true, calls to `die' from interactive code will invoke the Sepia
682 debugger. Default: true.
685 If true, calls to `warn' from interactive code will invoke the
686 Sepia debugger. Default: false.
689 If true, evaluate interactive expressions in list context.
693 Additional REPL shortcuts can be defined with
694 `Sepia::define_shortcut'. For example
696 Sepia::define_shortcut time => sub { print scalar localtime, "\n"; 0 },
697 'Display the current time.';
699 defines a shortcut "time" that displays the current time. For
700 details, see the code in `Sepia.pm'.
703 File: sepia.info, Node: Internals, Next: Credits, Prev: Customization, Up: Top
708 Many things remain unexplained except by the code itself, and some
709 details mentioned above should probably be given less prominence. For
710 developer documentation, please see the POD for `Sepia' and
711 `Sepia::Xref', and the doc-strings in `sepia.el'.
714 File: sepia.info, Node: Credits, Next: Function Index, Prev: Internals, Up: Top
720 Found and motivated me to fix a bunch of bugs, created Debian
723 Ævar Arnfjörð Bjarmason
724 Miscellaneous fixes. Tested unicode support.
727 Found and fixed numerous bugs.
730 Portions of the code were lifted from Emacs-w3m, SLIME, ido, and
731 B::Xref, all of which are Free software.
735 File: sepia.info, Node: Function Index, Prev: Credits, Up: Top
743 * sepia-apropos: Navigation. (line 60)
744 * sepia-callees: Navigation. (line 68)
745 * sepia-callers: Navigation. (line 64)
746 * sepia-complete-symbol: Completion. (line 34)
747 * sepia-cpan-doc: CPAN browsing. (line 22)
748 * sepia-cpan-install: CPAN browsing. (line 26)
749 * sepia-cpan-readme: CPAN browsing. (line 18)
750 * sepia-cpan-search: CPAN browsing. (line 14)
751 * sepia-defs: Navigation. (line 52)
752 * sepia-dwim: Navigation. (line 20)
753 * sepia-eval-defun: Evaluation. (line 12)
754 * sepia-eval-expression: Evaluation. (line 23)
755 * sepia-indent-or-complete: Completion. (line 40)
756 * sepia-install-eldoc: Documentation. (line 29)
757 * sepia-jump-to-symbol: Navigation. (line 36)
758 * sepia-load-file: Evaluation. (line 17)
759 * sepia-location: Navigation. (line 29)
760 * sepia-mode: Editing. (line 6)
761 * sepia-module-find: Navigation. (line 56)
762 * sepia-module-list: Documentation. (line 25)
763 * sepia-next: Navigation. (line 85)
764 * sepia-package-list: Documentation. (line 19)
765 * sepia-perl-ne-region: Mutilation. (line 17)
766 * sepia-perl-pe-region: Mutilation. (line 12)
767 * sepia-perldoc-this: Documentation. (line 12)
768 * sepia-perlize-region: Mutilation. (line 20)
769 * sepia-rebuild: Navigation. (line 89)
770 * sepia-repl: Interactive Perl. (line 6)
771 * sepia-scratch: Scratchpad. (line 6)
772 * sepia-set-cwd: Evaluation. (line 28)
773 * sepia-var-defs: Navigation. (line 76)
774 * sepia-var-uses: Navigation. (line 72)
775 * sepia-view-pod: Documentation. (line 16)
781 Node: Introduction
\x7f530
782 Node: Getting Started
\x7f951
783 Node: Philosophy
\x7f1576
784 Node: Editing
\x7f4582
785 Node: Completion
\x7f5044
786 Node: Navigation
\x7f6888
787 Node: Documentation
\x7f10237
788 Node: Interactive Perl
\x7f11784
789 Node: Shortcuts
\x7f12521
790 Node: Debugger
\x7f14722
791 Node: Evaluation
\x7f16381
792 Node: Mutilation
\x7f17357
793 Node: Scratchpad
\x7f18309
794 Node: CPAN browsing
\x7f18714
795 Node: Customization
\x7f19603
796 Node: Emacs Variables
\x7f19901
797 Node: Perl Variables
\x7f22396
798 Node: Internals
\x7f23883
799 Node: Credits
\x7f24243
800 Node: Function Index
\x7f24701