Sepia(3) Simple Emacs-Perl Interface

SYNOPSIS

From inside Emacs:


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

At the prompt in the "*sepia-repl*" buffer:

   main @> ,help

For more information, please see Sepia.html or sepia.info, which come with the distribution.

DESCRIPTION

Sepia is a set of features to make Emacs a better tool for Perl development. This package contains the Perl side of the implementation, including all user-serviceable parts (for the cross-referencing facility see Sepia::Xref). This document is aimed as Sepia developers; for user documentation, see Sepia.html or sepia.info.

Though not intended to be used independent of the Emacs interface, the Sepia module's functionality can be used through a rough procedural interface.

Hooks

Like Emacs, Sepia's behavior can be modified by placing functions on various hooks (arrays). Hooks can be manipulated by the following functions:
"add_hook(@hook, @functions)" --- Add @functions to @hook.
"remove_hook(@hook, @functions)" --- Remove named @functions from @hook.
"run_hook(@hook)" --- Run the functions on the named hook.
Each function is called with no arguments in an eval {} block, and its return value is ignored.

Sepia currently defines the following 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 hard to come up with a list of completions.
"$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.
"@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 e.g. ``S:m_w'' completes to ``Sepia::my_walksymtable''. If $sub is given, also consider 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.
"@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 --- I don't know if or how Perl distinguishes inner blocks.
"$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.
"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.
"\@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".
"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.

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.

AUTHOR

Sean O'Rourke, <[email protected]>

Bug reports welcome, patches even more welcome.

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.