--- name: "Sepia" section: "3pm" platform: "linux" package: "sepia" version: "0.992-8" release: "Debian 13 (Trixie)" platforms: ["linux"] url: "https://new.carta.tech/Sepia" --- # Sepia(3pm) Simple Emacs-Perl Interface ## 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 \. There are several modules for Perl development in Emacs on CPAN, including Devel::PerlySense and PDE. For a complete list, see \. ## AUTHOR Sean O'Rourke, \ 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.