Sepia(3pm)

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".