.\" Automatically generated by Pod::Man 4.07 (Pod::Simple 3.32)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" Set up some character translations and predefined strings.  \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote.  \*(C+ will
.\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
.\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
.\" nothing in troff, for use with C<>.
.tr \(*W-
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
.    ds -- \(*W-
.    ds PI pi
.    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
.    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
.    ds L" ""
.    ds R" ""
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds -- \|\(em\|
.    ds PI \(*p
.    ds L" ``
.    ds R" ''
.    ds C`
.    ds C'
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\"
.\" If the F register is >0, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.if !\nF .nr F 0
.if \nF>0 \{\
.    de IX
.    tm Index:\\$1\t\\n%\t"\\$2"
..
.    if !\nF==2 \{\
.        nr % 0
.        nr F 2
.    \}
.\}
.\" ========================================================================
.\"
.IX Title "Sepia 3pm"
.TH Sepia 3pm "2017-01-21" "perl v5.24.1" "User Contributed Perl Documentation"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH "NAME"
Sepia \- Simple Emacs\-Perl Interface
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
From inside Emacs:
.PP
.Vb 2
\&   M\-x load\-library RET sepia RET
\&   M\-x sepia\-repl RET
.Ve
.PP
At the prompt in the \f(CW\*(C`*sepia\-repl*\*(C'\fR buffer:
.PP
.Vb 1
\&   main @> ,help
.Ve
.PP
For more information, please see \fISepia.html\fR or \fIsepia.info\fR, which
come with the distribution.
.SH "DESCRIPTION"
.IX Header "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.
.PP
Though not intended to be used independent of the Emacs interface, the
Sepia module's functionality can be used through a rough procedural
interface.
.SS "Hooks"
.IX Subsection "Hooks"
Like Emacs, Sepia's behavior can be modified by placing functions on
various hooks (arrays).  Hooks can be manipulated by the following
functions:
.ie n .IP """add_hook(@hook, @functions)"" \*(-- Add @functions to @hook." 4
.el .IP "\f(CWadd_hook(@hook, @functions)\fR \*(-- Add \f(CW@functions\fR to \f(CW@hook\fR." 4
.IX Item "add_hook(@hook, @functions) Add @functions to @hook."
.PD 0
.ie n .IP """remove_hook(@hook, @functions)"" \*(-- Remove named @functions from @hook." 4
.el .IP "\f(CWremove_hook(@hook, @functions)\fR \*(-- Remove named \f(CW@functions\fR from \f(CW@hook\fR." 4
.IX Item "remove_hook(@hook, @functions) Remove named @functions from @hook."
.ie n .IP """run_hook(@hook)"" \*(-- Run the functions on the named hook." 4
.el .IP "\f(CWrun_hook(@hook)\fR \*(-- Run the functions on the named hook." 4
.IX Item "run_hook(@hook) Run the functions on the named hook."
.PD
Each function is called with no arguments in an eval {} block, and
its return value is ignored.
.PP
Sepia currently defines the following hooks:
.ie n .IP "@PRE_PROMPT \*(-- Called immediately before the prompt is printed." 4
.el .IP "\f(CW@PRE_PROMPT\fR \*(-- Called immediately before the prompt is printed." 4
.IX Item "@PRE_PROMPT Called immediately before the prompt is printed."
.PD 0
.ie n .IP "@PRE_EVAL \*(-- Called immediately before evaluating user input." 4
.el .IP "\f(CW@PRE_EVAL\fR \*(-- Called immediately before evaluating user input." 4
.IX Item "@PRE_EVAL Called immediately before evaluating user input."
.ie n .IP "@POST_EVAL \*(-- Called immediately after evaluating user input." 4
.el .IP "\f(CW@POST_EVAL\fR \*(-- Called immediately after evaluating user input." 4
.IX Item "@POST_EVAL Called immediately after evaluating user input."
.PD
.SS "Completion"
.IX Subsection "Completion"
Sepia tries hard to come up with a list of completions.
.ie n .IP """$re = _apropos_re($pat)""" 4
.el .IP "\f(CW$re = _apropos_re($pat)\fR" 4
.IX Item "$re = _apropos_re($pat)"
Create a completion expression from user input.
.ie n .IP """$val = filter_untyped""" 4
.el .IP "\f(CW$val = filter_untyped\fR" 4
.IX Item "$val = filter_untyped"
Return true if \f(CW$_\fR is the name of a sub, file handle, or package.
.ie n .IP """$val = filter_typed $type""" 4
.el .IP "\f(CW$val = filter_typed $type\fR" 4
.IX Item "$val = filter_typed $type"
Return true if \f(CW$_\fR is the name of something of \f(CW$type\fR, which
should be either a glob slot name (e.g. \s-1SCALAR\s0) or the special value
\&\*(L"\s-1VARIABLE\*(R",\s0 meaning an array, hash, or scalar.
.ie n .IP """$re_out = maybe_icase $re_in""" 4
.el .IP "\f(CW$re_out = maybe_icase $re_in\fR" 4
.IX Item "$re_out = maybe_icase $re_in"
Make \f(CW$re_in\fR case-insensitive if it looks like it should be.
.ie n .IP """@res = all_abbrev_completions $pattern""" 4
.el .IP "\f(CW@res = all_abbrev_completions $pattern\fR" 4
.IX Item "@res = all_abbrev_completions $pattern"
Find all \*(L"abbreviated completions\*(R" for \f(CW$pattern\fR.
.ie n .IP """@res = filter_exact_prefix @names""" 4
.el .IP "\f(CW@res = filter_exact_prefix @names\fR" 4
.IX Item "@res = filter_exact_prefix @names"
Filter exact matches so that e.g. \*(L"A::x\*(R" completes to \*(L"A::xx\*(R" when
both \*(L"Ay::xx\*(R" and \*(L"A::xx\*(R" exist.
.ie n .IP """@res = lexical_completions $type, $str, $sub""" 4
.el .IP "\f(CW@res = lexical_completions $type, $str, $sub\fR" 4
.IX Item "@res = lexical_completions $type, $str, $sub"
Find lexicals of \f(CW$sub\fR (or a parent lexical environment) of type
\&\f(CW$type\fR matching \f(CW$str\fR.
.ie n .IP """@compls = completions($string [, $type [, $sub ] ])""" 4
.el .IP "\f(CW@compls = completions($string [, $type [, $sub ] ])\fR" 4
.IX Item "@compls = completions($string [, $type [, $sub ] ])"
Find a list of completions for \f(CW$string\fR with glob type \f(CW$type\fR,
which may be \*(L"\s-1SCALAR\*(R", \*(L"HASH\*(R", \*(L"ARRAY\*(R", \*(L"CODE\*(R", \*(L"IO\*(R",\s0 or the special
value \*(L"\s-1VARIABLE\*(R",\s0 which means either scalar, hash, or array.
Completion operates on word subparts separated by [:_], so
e.g. \*(L"S:m_w\*(R" completes to \*(L"Sepia::my_walksymtable\*(R".  If \f(CW$sub\fR is
given, also consider its lexical variables.
.ie n .IP """@compls = method_completions($expr, $string [,$eval])""" 4
.el .IP "\f(CW@compls = method_completions($expr, $string [,$eval])\fR" 4
.IX Item "@compls = method_completions($expr, $string [,$eval])"
Complete among methods on the object returned by \f(CW$expr\fR.  The
\&\f(CW$eval\fR argument, if present, is a function used to do the
evaluation; the default is \f(CW\*(C`eval\*(C'\fR, but for example the Sepia \s-1REPL\s0
uses \f(CW\*(C`Sepia::repl_eval\*(C'\fR.  \fBWarning\fR: Since it has to evaluate
\&\f(CW$expr\fR, method completion can be extremely problematic.  Use with
care.
.ie n .IP """@matches = apropos($name [, $is_regex])""" 4
.el .IP "\f(CW@matches = apropos($name [, $is_regex])\fR" 4
.IX Item "@matches = apropos($name [, $is_regex])"
Search for function \f(CW$name\fR, either in all packages or, if \f(CW$name\fR
is qualified, only in one package.  If \f(CW$is_regex\fR is true, the
non-package part of \f(CW$name\fR is a regular expression.
.SS "Module information"
.IX Subsection "Module information"
.ie n .IP """@names = mod_subs($pack)""" 4
.el .IP "\f(CW@names = mod_subs($pack)\fR" 4
.IX Item "@names = mod_subs($pack)"
Find subs in package \f(CW$pack\fR.
.ie n .IP """@decls = mod_decls($pack)""" 4
.el .IP "\f(CW@decls = mod_decls($pack)\fR" 4
.IX Item "@decls = mod_decls($pack)"
Generate a list of declarations for all subroutines in package
\&\f(CW$pack\fR.
.ie n .IP """$info = module_info($module, $type)""" 4
.el .IP "\f(CW$info = module_info($module, $type)\fR" 4
.IX Item "$info = module_info($module, $type)"
Emacs-called function to get module information.
.ie n .IP """$file = mod_file($mod)""" 4
.el .IP "\f(CW$file = mod_file($mod)\fR" 4
.IX Item "$file = mod_file($mod)"
Find the likely file owner for module \f(CW$mod\fR.
.ie n .IP """@mods = package_list""" 4
.el .IP "\f(CW@mods = package_list\fR" 4
.IX Item "@mods = package_list"
Gather a list of all distributions on the system.
.ie n .IP """@mods = module_list""" 4
.el .IP "\f(CW@mods = module_list\fR" 4
.IX Item "@mods = module_list"
Gather a list of all packages (.pm files, really) installed on the
system, grouped by distribution. \s-1XXX UNUSED\s0
.ie n .IP """@paths = file_list $module""" 4
.el .IP "\f(CW@paths = file_list $module\fR" 4
.IX Item "@paths = file_list $module"
List the absolute paths of all files (except man pages) installed by
\&\f(CW$module\fR.
.ie n .IP """@mods = doc_list""" 4
.el .IP "\f(CW@mods = doc_list\fR" 4
.IX Item "@mods = doc_list"
Gather a list of all documented packages (.?pm files, really)
installed on the system, grouped by distribution. \s-1XXX UNUSED\s0
.SS "Miscellaneous functions"
.IX Subsection "Miscellaneous functions"
.ie n .IP """$v = core_version($module)""" 4
.el .IP "\f(CW$v = core_version($module)\fR" 4
.IX Item "$v = core_version($module)"
.PD 0
.ie n .IP """[$file, $line, $name] = location($name)""" 4
.el .IP "\f(CW[$file, $line, $name] = location($name)\fR" 4
.IX Item "[$file, $line, $name] = location($name)"
.PD
Return a [file, line, name] triple for function \f(CW$name\fR.
.ie n .IP """lexicals($subname)""" 4
.el .IP "\f(CWlexicals($subname)\fR" 4
.IX Item "lexicals($subname)"
Return a list of \f(CW$subname\fR's lexical variables.  Note that this
includes all nested scopes \*(-- I don't know if or how Perl
distinguishes inner blocks.
.ie n .IP """$lisp = tolisp($perl)""" 4
.el .IP "\f(CW$lisp = tolisp($perl)\fR" 4
.IX Item "$lisp = tolisp($perl)"
Convert a Perl scalar to some ELisp equivalent.
.ie n .IP """printer(\e@res)""" 4
.el .IP "\f(CWprinter(\e@res)\fR" 4
.IX Item "printer(@res)"
Print \f(CW@res\fR appropriately on the current filehandle.  If \f(CW$ISEVAL\fR
is true, use terse format.  Otherwise, use human-readable format,
which can use either Data::Dumper, \s-1YAML\s0, or Data::Dump.
.ie n .IP """prompt()"" \*(-- Print the \s-1REPL\s0 prompt." 4
.el .IP "\f(CWprompt()\fR \*(-- Print the \s-1REPL\s0 prompt." 4
.IX Item "prompt() Print the REPL prompt."
.PD 0
.ie n .IP """$flowed = flow($width, $text)"" \*(-- Flow $text to at most $width columns." 4
.el .IP "\f(CW$flowed = flow($width, $text)\fR \*(-- Flow \f(CW$text\fR to at most \f(CW$width\fR columns." 4
.IX Item "$flowed = flow($width, $text) Flow $text to at most $width columns."
.PD
.SS "Persistence"
.IX Subsection "Persistence"
.ie n .IP """load \e@keyvals"" \*(-- Load persisted data in @keyvals." 4
.el .IP "\f(CWload \e@keyvals\fR \*(-- Load persisted data in \f(CW@keyvals\fR." 4
.IX Item "load @keyvals Load persisted data in @keyvals."
.PD 0
.ie n .IP """$ok = saveable $name"" \*(-- Return whether $name is saveable." 4
.el .IP "\f(CW$ok = saveable $name\fR \*(-- Return whether \f(CW$name\fR is saveable." 4
.IX Item "$ok = saveable $name Return whether $name is saveable."
.PD
Saving certain magic variables leads to badness, so we avoid them.
.ie n .IP """\e@kvs = save $re"" \*(-- Return a list of name/value pairs to save." 4
.el .IP "\f(CW\e@kvs = save $re\fR \*(-- Return a list of name/value pairs to save." 4
.IX Item "@kvs = save $re Return a list of name/value pairs to save."
.SS "\s-1REPL\s0 shortcuts"
.IX Subsection "REPL shortcuts"
The function implementing built-in \s-1REPL\s0 shortcut \*(L",X\*(R" is named \f(CW\*(C`repl_X\*(C'\fR.
.ie n .IP """define_shortcut $name, $sub [, $doc [, $shortdoc]]""" 4
.el .IP "\f(CWdefine_shortcut $name, $sub [, $doc [, $shortdoc]]\fR" 4
.IX Item "define_shortcut $name, $sub [, $doc [, $shortdoc]]"
Define \f(CW$name\fR as a shortcut for function \f(CW$sub\fR.
.ie n .IP """alias_shortcut $new, $old""" 4
.el .IP "\f(CWalias_shortcut $new, $old\fR" 4
.IX Item "alias_shortcut $new, $old"
Alias \f(CW$new\fR to do the same as \f(CW$old\fR.
.ie n .IP """define_shortcuts()""" 4
.el .IP "\f(CWdefine_shortcuts()\fR" 4
.IX Item "define_shortcuts()"
Define the default \s-1REPL\s0 shortcuts.
.ie n .IP """repl_strict([$value])""" 4
.el .IP "\f(CWrepl_strict([$value])\fR" 4
.IX Item "repl_strict([$value])"
Toggle strict mode.  Requires PadWalker and Devel::LexAlias.
.ie n .IP """repl_time([$value])""" 4
.el .IP "\f(CWrepl_time([$value])\fR" 4
.IX Item "repl_time([$value])"
Toggle command timing.
.ie n .IP """who($package [, $re])""" 4
.el .IP "\f(CWwho($package [, $re])\fR" 4
.IX Item "who($package [, $re])"
List variables and functions in \f(CW$package\fR matching \f(CW$re\fR, or all
variables if \f(CW$re\fR is absent.
.ie n .IP """$text = columnate(@items)""" 4
.el .IP "\f(CW$text = columnate(@items)\fR" 4
.IX Item "$text = columnate(@items)"
Format \f(CW@items\fR in columns such that they fit within \f(CW$ENV{COLUMNS}\fR
columns.
.ie n .IP """@m = methods($package [, $qualified])""" 4
.el .IP "\f(CW@m = methods($package [, $qualified])\fR" 4
.IX Item "@m = methods($package [, $qualified])"
List method names in \f(CW$package\fR and its parents.  If \f(CW$qualified\fR,
return full \*(L"\s-1CLASS::NAME\*(R"\s0 rather than just \*(L"\s-1NAME.\*(R"\s0
.ie n .IP """sig_warn($warning)""" 4
.el .IP "\f(CWsig_warn($warning)\fR" 4
.IX Item "sig_warn($warning)"
Collect \f(CW$warning\fR for later printing.
.ie n .IP """print_warnings()""" 4
.el .IP "\f(CWprint_warnings()\fR" 4
.IX Item "print_warnings()"
Print and clear accumulated warnings.
.ie n .IP """repl()""" 4
.el .IP "\f(CWrepl()\fR" 4
.IX Item "repl()"
Execute a command interpreter on standard input and standard output.
If you want to use different descriptors, localize them before
calling \f(CW\*(C`repl()\*(C'\fR.  The prompt has a few bells and whistles, including:
.RS 4
.IP "Obviously-incomplete lines are treated as multiline input (press 'return' twice or 'C\-c' to discard)." 4
.IX Item "Obviously-incomplete lines are treated as multiline input (press 'return' twice or 'C-c' to discard)."
.PD 0
.ie n .IP """die"" is overridden to enter a debugging repl at the point ""die"" is called." 4
.el .IP "\f(CWdie\fR is overridden to enter a debugging repl at the point \f(CWdie\fR is called." 4
.IX Item "die is overridden to enter a debugging repl at the point die is called."
.RE
.RS 4
.PD
.Sp
Behavior is controlled in part through the following package-globals:
.ie n .IP "$PACKAGE \*(-- evaluation package" 4
.el .IP "\f(CW$PACKAGE\fR \*(-- evaluation package" 4
.IX Item "$PACKAGE evaluation package"
.PD 0
.ie n .IP "$PRINTER \*(-- result printer (default: dumper)" 4
.el .IP "\f(CW$PRINTER\fR \*(-- result printer (default: dumper)" 4
.IX Item "$PRINTER result printer (default: dumper)"
.ie n .IP "$PS1 \*(-- the default prompt" 4
.el .IP "\f(CW$PS1\fR \*(-- the default prompt" 4
.IX Item "$PS1 the default prompt"
.ie n .IP "$STRICT \*(-- whether 'use strict' is applied to input" 4
.el .IP "\f(CW$STRICT\fR \*(-- whether 'use strict' is applied to input" 4
.IX Item "$STRICT whether 'use strict' is applied to input"
.ie n .IP "$WANTARRAY \*(-- evaluation context" 4
.el .IP "\f(CW$WANTARRAY\fR \*(-- evaluation context" 4
.IX Item "$WANTARRAY evaluation context"
.ie n .IP "$COLUMNATE \*(-- format some output nicely (default = 1)" 4
.el .IP "\f(CW$COLUMNATE\fR \*(-- format some output nicely (default = 1)" 4
.IX Item "$COLUMNATE format some output nicely (default = 1)"
.PD
Format some values nicely, independent of \f(CW$PRINTER\fR.  Currently, this
displays arrays of scalars as columns.
.ie n .IP "$REPL_LEVEL \*(-- level of recursive \fIrepl()\fR calls" 4
.el .IP "\f(CW$REPL_LEVEL\fR \*(-- level of recursive \fIrepl()\fR calls" 4
.IX Item "$REPL_LEVEL level of recursive repl() calls"
If zero, then initialization takes place.
.ie n .IP "%REPL \*(-- maps shortcut names to handlers" 4
.el .IP "\f(CW%REPL\fR \*(-- maps shortcut names to handlers" 4
.IX Item "%REPL maps shortcut names to handlers"
.PD 0
.ie n .IP "%REPL_DOC \*(-- maps shortcut names to documentation" 4
.el .IP "\f(CW%REPL_DOC\fR \*(-- maps shortcut names to documentation" 4
.IX Item "%REPL_DOC maps shortcut names to documentation"
.ie n .IP "%REPL_SHORT \*(-- maps shortcut names to brief usage" 4
.el .IP "\f(CW%REPL_SHORT\fR \*(-- maps shortcut names to brief usage" 4
.IX Item "%REPL_SHORT maps shortcut names to brief usage"
.RE
.RS 4
.RE
.PD
.SS "Module browsing"
.IX Subsection "Module browsing"
.ie n .IP """$status = html_module_list([$file [, $prefix]])""" 4
.el .IP "\f(CW$status = html_module_list([$file [, $prefix]])\fR" 4
.IX Item "$status = html_module_list([$file [, $prefix]])"
Generate an \s-1HTML\s0 list of installed modules, looking inside of
packages.  If \f(CW$prefix\fR is missing, uses \*(L"about://perldoc/\*(R".  If
\&\f(CW$file\fR is given, write the result to \f(CW$file\fR; otherwise, return it as a
string.
.ie n .IP """$status = html_package_list([$file [, $prefix]])""" 4
.el .IP "\f(CW$status = html_package_list([$file [, $prefix]])\fR" 4
.IX Item "$status = html_package_list([$file [, $prefix]])"
Generate an \s-1HTML\s0 list of installed top-level modules, without looking
inside of packages.  If \f(CW$prefix\fR is missing, uses
\&\*(L"about://perldoc/\*(R".  \f(CW$file\fR is the same as for \f(CW\*(C`html_module_list\*(C'\fR.
.SH "TODO"
.IX Header "TODO"
See the \s-1README\s0 file included with the distribution.
.SH "SEE ALSO"
.IX Header "SEE ALSO"
Sepia's public \s-1GIT\s0 repository is located at <http://repo.or.cz/w/sepia.git>.
.PP
There are several modules for Perl development in Emacs on \s-1CPAN,\s0
including Devel::PerlySense and \s-1PDE\s0.  For a complete list, see
<http://emacswiki.org/cgi\-bin/wiki/PerlLanguage>.
.SH "AUTHOR"
.IX Header "AUTHOR"
Sean O'Rourke, <seano@cpan.org>
.PP
Bug reports welcome, patches even more welcome.
.SH "COPYRIGHT"
.IX Header "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.