SEPIA: Simple Emacs Perl Integration



1 Introduction


1.1 Getting Started


     (defalias 'perl-mode 'sepia-mode)
     (require 'sepia)


1.2 Philosophy






1.3 Related Work





Stylish is a similar effort with a very different implementation philosophy, requiring maximal rather than minimal dependencies in both Perl and Emacs, and reimplementing comint in Emacs.

2 Editing


2.1 Completion



  2. If it looks like a variable (e.g. `%hash' or `$scalar'), complete first on lexical, then global variables.
  3. Complete on modules and functions.
  4. Otherwise, complete on Perl built-in operators.

For each of the first three cases, completions candidates are first generated by splitting the text on characters [:_] and matching the resulting word parts. For example, `X:a_b' will complete to all symbols matching `^X[^:]*:+a[^:_]*_b' such as `Xref::a_bug' and `X::always_bites_me'. If the module parts of the input match a module exactly and completions exist, they are not expanded. For example, `X:a' will expand only to `X::aa' when `X::aa' and `Xx::aa' exist. If no matches result, the text is treated as an acronym. For example, `dry' will complete to `dont_repeat_yourself'. Note: partial-word completion is not currently supported for lexicals.

Completion is performed by the following commands:

M-x sepia-complete-symbol
Complete the symbol before point as described above. This is always case-sensitive, independent of completion-ignore-case.
M-x sepia-indent-or-complete

2.2 Navigation



M-. M-.
M-x sepia-dwim
M-. d
M-x sepia-location
M-. j
M-x sepia-jump-to-symbol
M-. l
M-x sepia-pod-follow-link-at-point
Follow the POD link (L<...>) at point, or prompt for a link if there is none. Go to the appropriate location in the document source or, with a prefix argument, in the rendered documentation. This can be especially useful when writing links in your own documentation.


M-. f name <RET>
M-x sepia-defs
Find definition(s) of function name.
M-. m name <RET>
M-x sepia-module-find name <RET>
Find the source of module name.
M-. a regexp <RET>
M-x sepia-apropos regexp <RET>
Find definitions of all functions whose names match regexp.
M-x sepia-apropos-module regexp <RET>
Find all installed modules matching regexp. This function may be slow the first time it is called, because it has to build a list of installed modules.
M-. c name <RET>
M-x sepia-callers name <RET>
(Xref) Find calls to function name.
M-. C name <RET>
M-x sepia-callees name <RET>
(Xref) Find the definitions of functions called by name.
M-. v name <RET>
M-x sepia-var-uses name <RET>
(Xref) Find uses of the global variable name.
M-. V name <RET>
M-x sepia-var-defs name <RET>


M-x sepia-next
M-. r
M-x sepia-rebuild
M-. t
M-x find-tag

2.3 Documentation


M-. p name <RET>
M-x sepia-perldoc-this
View documentation for module name or Perl manual page name.
C-c C-d
M-x sepia-view-pod
Format and view the current buffer's documentation.



2.4 Other commands

M-x sepia-rename-lexical
Rename a variable in the function at point, querying for each replacement when called with a prefix argument. Currently, this is only a thin wrapper around query-replace.

3 Interactive Perl



Finally, Sepia comes with the sepl program, a standalone REPL that can be run from the command-line, and provides many features of the Emacs-based REPL.

3.1 Shortcuts

“Shortcuts” are commands handled specially by the REPL rather than being evaluated as Perl code. They either communicate with the REPL function, or provide a convenient interface to Sepia variables and functions. Shortcuts are prefixed by a comma (<,>), and may be abbreviated to the shortest unique prefix. The debugger defines additional shortcuts (See Debugger.).

break file:line [expr]
cd dir
Change Perl's current directory to dir.
debug [val]
define name ['doc'] body...
format type
Set the output format to type, either “dumper” (using Data::Dumper), “dump” (Data::Dump), “yaml” (YAML), “peek” (Devel::Peek), “dumpvar” (, somewhat rough), or “plain” (stringification). Default: “dumper”.

Note that this setting is independent of $COLUMNATE and $STRINGIFY.

Display a list of shortcuts.
load [file]
Reload saved variables from file (or ~/.sepia-save), created by save.
List breakpoints.
lsmod [pattern]
List currently-loaded modules matching optional pattern.
methods name [regexp]
package name
Set the default evaluation package to name.
Show the process's current working directory.
Exit the inferior Perl process.
reload [module | /pattern/]
Reload module (but not its dependencies), or all modules matching pattern.
freload module
Reload module and all of its dependencies.
Reload and recursively invoke the REPL. This command is mostly of interest when working on Sepia itself, and will fail catastrophically if fails to compile.
save [pattern [file]]
Save variables matching pattern (or all variables) to file (or ~/.sepia-save) in Storable format. Note that because saving magic variables can have unpredictable results, using save without a pattern argument is risky. Sepia excludes common magic variables and dangerous packages, but its list is not foolproof.
shell [command]
size package [regexp]
size [regexp]
List the variables in package (or the current package) along with their total sizes. This requires the Devel::Size module. In strict mode, list lexical variables if no package is given.
strict [val]
test [file]
Run tests in the current directory. If file is given, only run test file or t/file
time [val]
Set time display to val, or toggle it if val is not given. With time display enabled, Sepia will use BSD::Resource and/or Time::HiRes to display wall clock time and CPU usage for the previous command as part of the prompt.
undef name
wantarray [val]
Set the evaluation context to val: @ means array, $ means scalar, and anything else means void.
who package [regexp]
who [regexp]
List identifiers in package (main by default) matching optional regexp. In strict mode, list lexical variables if no package is given.

3.2 Debugger



Show a backtrace.
Delete the current breakpoint.
down n
up n
inspect [n]
next [n]
Advance n (or one) lines, skipping subroutine calls.
return expr
step [n]
xreturn sub expr

3.3 Evaluation


M-x sepia-eval-defun
C-c C-l
M-x sepia-load-file
C-c e
Set the REPL's working directory to the current buffer's directory.

3.4 Mutilation


Evaluate code as above, but collect the results instead.

3.5 Scratchpad


4 CPAN browsing


List modules whose names match pattern.
List modules whose names or descriptions match pattern.
List modules authored by name.
Fetch and display module's README file.
Browse module's documentation on

5 Customization


5.1 Emacs Customization



5.2 Perl Customization



If true, columnate simple arrays independent of the value of $PRINTER. Default: true.
If true, stringify objects that overload the operation independent of the value of $PRINTER. Default: true.
If @, evaluate interactive expressions in list context, if $, scalar, otherwise, void. Default: @.

Additional REPL shortcuts can be defined as follows:

Sepia::define_shortcut name, function [, shortdoc [, longdoc]]
Define a shortcut name to call function. Also define a short usage message shortdoc and documentation longdoc. For example,
          Sepia::define_shortcut time => sub { print scalar localtime, "\n" },
              'time', 'Display the current time.';

defines a shortcut “time” that displays the current time. For more examples, see the function define_shortcuts code in

Sepia::alias_shortcut new, old
Make new an alias for old.

6 Internals



Can I use Sepia outside of Emacs?
Sepia comes with the sepl program, a command-line REPL using the Sepia::Readline module, that provides many features of the Emacs-based REPL. It could be improved, though – patches welcome!

sepl currently provides completion for Term::ReadLine::Gnu and Term::ReadLine::Perl. If you have neither of these, using rlwrap might be the best option.

Why is the documentation in TeXInfo format?!
TeXInfo is the worst form of documentation, except for all the others. TeX and LaTeX produce beautiful printed output, and Info is the best way to view documentation in Emacs for things that are not themselves part of Emacs (i.e. “can have docstrings”).

It's awful to edit, being both verbose and redundant – just look at AUCTeX's texinfo-every-node-update for desperate placation of the suck, then try to figure out what's wrong when makeinfo complains about texinfo-every-node-update's output – but it's what we have. At least it sucks less than DocBook, raw HTML, or troff.


Hilko Bengen
Ævar Arnfjörð Bjarmason
Miscellaneous fixes. Tested unicode support.
Ye Wenbin
Found and fixed numerous bugs.
Free Software

Function Index

Variable Index


[1] In my brief experience with Visual Studio, I was struck by the fact that I saw several toolbars, a couple of navigation windows, and a tiny view of the actual code. Sometimes a tooltip would obscure part of that tiny window.