Sepia(3pm)

💖 NAME 💖

Sepia — Simple Emacs-Perl Interface. that's it, that's the vibe 🦋

---

✨ SYNOPSIS ✨

okay bestie, from inside Emacs:

M-x load-library RET sepia RET
M-x sepia-repl RET

and then at the prompt in the "*sepia-repl*" buffer:

main @> ,help

want more? the whole tea is in Sepia.html or sepia.info, both of which ship with the distribution. go read those, they ate 💅

---

🌸 DESCRIPTION 🌸

so Sepia is a whole set of features whose entire job is making Emacs a better tool for Perl development. this package has the Perl side of the implementation — including all the user-serviceable parts (for the cross-referencing facility you want Sepia::Xref, different page, different queen 👑).

heads up: this document is aimed at Sepia developers. if you're here as a user, you want Sepia.html or sepia.info instead, no cap.

and like, it's not meant to be used independent of the Emacs interface, but the Sepia module's functionality can still be reached through a rough procedural interface. so if you wanna get feral with it, you can 🫶

🎀 Hooks

just like Emacs, Sepia's behavior is modifiable by placing functions on various hooks (arrays). hooks get manipulated with these functions:

• add_hook(@hook, @functions) — add @functions to @hook.
• remove_hook(@hook, @functions) — remove the named @functions from @hook.
• run_hook(@hook) — run the functions on the named hook.
  • each function gets called with no arguments inside an eval {} block, and its return value is just… ignored. it's giving "we don't care what you say, we only care that you showed up" 😭

Sepia currently defines these hooks:

• @PRE_PROMPT — called immediately before the prompt is printed.
• @PRE_EVAL — called immediately before evaluating user input.
• @POST_EVAL — called immediately after evaluating user input.

🦋 Completion

Sepia tries so hard to come up with a list of completions. respect the effort.

• $re = _apropos_re($pat) — create a completion expression from user input.
• $val = filter_untyped — return true if $_ is the name of a sub, file handle, or package.
• $val = filter_typed $type — return true if $_ is the name of something of $type, which should be either a glob slot name (e.g. SCALAR) or the special value "VARIABLE", meaning an array, hash, or scalar.
• $re_out = maybe_icase $re_in — make $re_in case-insensitive if it looks like it should be. vibe check based, honestly.
• @res = all_abbrev_completions $pattern — find all "abbreviated completions" for $pattern.
• @res = filter_exact_prefix @names — filter exact matches so that e.g. "A::x" completes to "A::xx" when both "Ay::xx" and "A::xx" exist.
• @res = lexical_completions $type, $str, $sub — find lexicals of $sub (or a parent lexical environment) of type $type matching $str.
• @compls = completions($string [, $type [, $sub ] ]) — find a list of completions for $string with glob type $type, which may be "SCALAR", "HASH", "ARRAY", "CODE", "IO", or the special value "VARIABLE", which means either scalar, hash, or array. completion operates on word subparts separated by [:_], so like, "S:m_w" completes to "Sepia::my_walksymtable". iconic. if $sub is given, it also considers its lexical variables.
• @compls = method_completions($expr, $string [,$eval]) — complete among methods on the object returned by $expr. the $eval argument, if present, is a function used to do the evaluation; the default is "eval", but for example the Sepia REPL uses "Sepia::repl_eval".

⚠️ warning: since it has to evaluate $expr, method completion can be extremely problematic. use with care, bestie. fr fr.

• @matches = apropos($name [, $is_regex]) — search for function $name, either in all packages or, if $name is qualified, only in one package. if $is_regex is true, the non-package part of $name is a regular expression.

⭐ Module information

• @names = mod_subs($pack) — find subs in package $pack.
• @decls = mod_decls($pack) — generate a list of declarations for all subroutines in package $pack.
• $info = module_info($module, $type) — Emacs-called function to get module information.
• $file = mod_file($mod) — find the likely file owner for module $mod.
• @mods = package_list — gather a list of all distributions on the system.
• @mods = module_list — gather a list of all packages (.pm files, really) installed on the system, grouped by distribution. XXX UNUSED
• @paths = file_list $module — list the absolute paths of all files (except man pages) installed by $module.
• @mods = doc_list — gather a list of all documented packages (.?pm files, really) installed on the system, grouped by distribution. XXX UNUSED

💜 Miscellaneous functions

• $v = core_version($module)
• [$file, $line, $name] = location($name) — return a [file, line, name] triple for function $name.
• lexicals($subname) — return a list of $subname's lexical variables. note that this includes all nested scopes — the author genuinely does not know if or how Perl distinguishes inner blocks, and honestly? same 💀
• $lisp = tolisp($perl) — convert a Perl scalar to some ELisp equivalent.
• printer(\@res) — print @res appropriately on the current filehandle. if $ISEVAL is true, use terse format. otherwise, use human-readable format, which can use either Data::Dumper, YAML, or Data::Dump. choices, choices ✨
• prompt() — print the REPL prompt.
• $flowed = flow($width, $text) — flow $text to at most $width columns.

🍓 Persistence

• load \@keyvals — load persisted data in @keyvals.
• $ok = saveable $name — return whether $name is saveable.
  • saving certain magic variables leads to badness, so we avoid them. protecting you from yourself, bestie 🫶
• \@kvs = save $re — return a list of name/value pairs to save.

👑 REPL shortcuts

the function implementing built-in REPL shortcut ,X is named repl_X. cute naming convention, no notes.

• define_shortcut $name, $sub [, $doc [, $shortdoc]] — define $name as a shortcut for function $sub.
• alias_shortcut $new, $old — alias $new to do the same as $old.
• define_shortcuts() — define the default REPL shortcuts.
• repl_strict([$value]) — toggle strict mode. requires PadWalker and Devel::LexAlias.
• repl_time([$value]) — toggle command timing.
• who($package [, $re]) — list variables and functions in $package matching $re, or all variables if $re is absent.
• $text = columnate(@items) — format @items in columns such that they fit within $ENV{COLUMNS} columns.
• @m = methods($package [, $qualified]) — list method names in $package and its parents. if $qualified, return full "CLASS::NAME" rather than just "NAME."
• sig_warn($warning) — collect $warning for later printing.
• print_warnings() — print and clear accumulated warnings.
• repl() — execute a command interpreter on standard input and standard output. if you want to use different descriptors, localize them before calling repl(). the prompt has a few bells and whistles, including:
  • obviously-incomplete lines are treated as multiline input (press 'return' twice or 'C-c' to discard).
  • "die" is overridden to enter a debugging repl at the point "die" is called. yes really, slay.

behavior is controlled in part through the following package-globals:

• $PACKAGE — evaluation package
• $PRINTER — result printer (default: dumper)
• $PS1 — the default prompt
• $STRICT — whether 'use strict' is applied to input
• $WANTARRAY — evaluation context
• $COLUMNATE — format some output nicely (default = 1)
  • format some values nicely, independent of $PRINTER. currently, this displays arrays of scalars as columns.
• $REPL_LEVEL — level of recursive repl() calls
  • if zero, then initialization takes place.
• %REPL — maps shortcut names to handlers
• %REPL_DOC — maps shortcut names to documentation
• %REPL_SHORT — maps shortcut names to brief usage

🌈 Module browsing

• $status = html_module_list([$file [, $prefix]]) — generate an HTML list of installed modules, looking inside of packages. if $prefix is missing, uses "about://perldoc/". if $file is given, write the result to $file; otherwise, return it as a string.
• $status = html_package_list([$file [, $prefix]]) — generate an HTML list of installed top-level modules, without looking inside of packages. if $prefix is missing, uses "about://perldoc/". $file is the same as for "html_module_list".

---

🌸 TODO 🌸

see the README file included with the distribution. (they're keeping the tea in there, not here 🙈)

---

💅 SEE ALSO 💅

Sepia's public GIT repository is located at <http://repo.or.cz/w/sepia.git>.

there are several modules for Perl development in Emacs on CPAN, including Devel::PerlySense and PDE. for a complete list, see <http://emacswiki.org/cgi-bin/wiki/PerlLanguage>.

---

🦋 AUTHOR 🦋

Sean O'Rourke, <seano@cpan.org>

bug reports welcome, patches even more welcome. that's the energy, honestly 🔥

---

💜 COPYRIGHT 💜

Copyright (C) 2005-2011 Sean O'Rourke. all rights reserved, some wrongs reversed. this module is distributed under the same terms as Perl itself.

---

okay that's the whole page, mwah 🎀 this was perl v5.34.0, dated 2022-06-26, and it's the Sepia(3pm) page — go forth and make Emacs love Perl as much as we do. bye bestie 💖✨