NAME¶
Sepia - 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.
- "@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.
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
<
http://emacswiki.org/cgi-bin/wiki/PerlLanguage>.
AUTHOR¶
Sean O'Rourke, <seano@cpan.org>
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.