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.

   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.

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.

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.