From 5902100790454bfe5e5b030d0ad9dc37e791cc00 Mon Sep 17 00:00:00 2001 From: Sean O'Rourke Date: Mon, 4 Oct 2010 12:08:26 -0700 Subject: [PATCH] see ChangeLog --- ChangeLog | 22 ++++++++ README | 14 +++-- lib/Sepia.pm | 103 ++++++++++++++++++++++++++++++----- package.sh | 4 +- sepia.el | 96 ++++++++++++++++++++++++++++++--- sepia.info | 171 ++++++++++++++++++++++++++++++++++++++--------------------- sepia.texi | 75 ++++++++++++++++++++------ 7 files changed, 383 insertions(+), 102 deletions(-) diff --git a/ChangeLog b/ChangeLog index 6bec8b7..f7e7118 100644 --- a/ChangeLog +++ b/ChangeLog @@ -1,3 +1,25 @@ +2010-10-04 Sean O'Rourke + + * sepia.el (sepia-perldoc-this): Display documentation in a less + annoying way. + (cperl-imenu--create-perl-index): Advise it to strip out some entries. + + * Sepia.pm: dumpvar.pl and Devel::Peek format options. + +2010-09-21 Sean O'Rourke + + * lib/Sepia.pm (track_requires): New function. + (file_list): New function. + Add 'dumpvar' flavor of output. + (repl_lsmod): New function. + (requires,users): Use track_requires. + + * sepia.el (sepia-dired-package): New function. + (sepia-skip-doc-scan): New variable. + (sepia-doc-update): Use previous to skip confusing files. + (sepia-find-loaded-modules): New function. + (cperl-imenu--create-perl-index): Filter cruft. + 2010-09-13 Sean O'Rourke * sepia.el (sepia-doc-scan-buffer): Avoid spurious matches. diff --git a/README b/README index b6ad1d7..f47532d 100644 --- a/README +++ b/README @@ -53,8 +53,7 @@ Emacs-style ChangeLog entry. * TODO ** (Medium) Get the variable def/use analysis working again. ** (Medium) Let sepia-next go backward - Need to use a vector plus current index instead of a list for - sepia-found. +Remove the current garbage and use next-error all the time. ** (Hard) return from anything in the debugger Make it possible to return from intermediate calls in the debugger. Returning from die() is not often useful. @@ -77,6 +76,10 @@ Emacs-style ChangeLog entry. multi-line statements, etc. Fix this somehow. One way might be to temporary regain control on a op_next/op_nextstate, or whatever those are called, but this would be hard and/or require XS. + + If we set $^P to populate @dbline, we can use that to find + breakable lines, but that still doesn't fix backward branches in + loops. ** (Medium) Make "finish" more reliable It currently assumes that the last breakable statement in a sub is one line before its end. The "right" solution would be like above: @@ -105,7 +108,12 @@ reproduce, with the dates they were first observed. in listings for every instance of "new" in your program. ** (2008-01-18) the first value printed in the debugger is undef. why?! ** (2009-12-13) completion deletes things it shouldn't - e.g. $x->method => method. I need to rewrite this code to not suck. + e.g. $x->method => method. I need to rewrite this code to not + suck. +** (2010-09-30) broken in view-mode + should scroll up if you enable view-mode, but for + whatever reason it stays bound to hungry-delete. I'm not sure if + this is my fault, or cperl's. * COPYRIGHT AND LICENCE Copyright (C) 2004-2010 Sean O'Rourke diff --git a/lib/Sepia.pm b/lib/Sepia.pm index 343c37d..c1c7bcf 100644 --- a/lib/Sepia.pm +++ b/lib/Sepia.pm @@ -40,6 +40,17 @@ BEGIN { eval 'use strict'; } no warnings 'deprecated'; # undo some of the 5.12 suck. + # Not as useful as I had hoped... + sub track_requires + { + my $parent = caller; + (my $child = $_[1]) =~ s!/!::!g; + $child =~ s/\.pm$//; + push @{$REQUIRED_BY{$child}}, $parent; + push @{$REQUIRES{$parent}}, $child; + } + BEGIN { sub TRACK_REQUIRES () { $ENV{TRACK_REQUIRES}||0 } }; + unshift @INC, \&Sepia::track_requires if TRACK_REQUIRES; } use B; use Sepia::Debug; # THIS TURNS ON DEBUGGING INFORMATION! @@ -50,9 +61,10 @@ use File::Find; use Storable qw(store retrieve); use vars qw($PS1 %REPL %RK %REPL_DOC %REPL_SHORT %PRINTER - @res $REPL_LEVEL $REPL_QUIT $PACKAGE - $WANTARRAY $PRINTER $STRICT $COLUMNATE $ISEVAL - $LAST_INPUT $READLINE @PRE_EVAL @POST_EVAL @PRE_PROMPT); + @res $REPL_LEVEL $REPL_QUIT $PACKAGE $SIGGED + $WANTARRAY $PRINTER $STRICT $COLUMNATE $ISEVAL $STRINGIFY + $LAST_INPUT $READLINE @PRE_EVAL @POST_EVAL @PRE_PROMPT + %REQUIRED_BY %REQUIRES); BEGIN { eval q{ use List::Util 'max' }; @@ -582,6 +594,19 @@ sub module_list } @_; } +=item C<@paths = file_list $module> + +List the absolute paths of all files (except man pages) installed by +C<$module>. + +=cut + +sub file_list +{ + my @ret = eval { grep /\.p(l|m|od)$/, inst->files(shift) }; + @ret ? @ret : (); +} + =item C<@mods = doc_list> Gather a list of all documented packages (.?pm files, really) @@ -731,24 +756,27 @@ which can use either L, L, or L. my $thing = @res > 1 ? \@res : $res[0]; eval { $_ = Data::Dumper::Dumper($thing); - s/^\$VAR1 = //; - s/;$//; }; if (length $_ > ($ENV{COLUMNS} || 80)) { $Data::Dumper::Indent = 1; eval { $_ = Data::Dumper::Dumper($thing); - s/\A\$VAR1 = //; - s/;\Z//; }; - s/\A\$VAR1 = //; - s/;\Z//; } + s/\A\$VAR1 = //; + s/;\Z//; $_; }, plain => sub { "@res"; }, + dumpvar => sub { + if (eval q{require 'dumpvar.pl';1}) { + dumpvar::veryCompact(1); + $PRINTER{dumpvar} = sub { dumpValue(\@res) }; + goto &{$PRINTER{dumpvar}}; + } + }, yaml => sub { eval q{ require YAML }; if ($@) { @@ -800,7 +828,8 @@ sub printer my $str; if ($ISEVAL) { $res = "@res"; - } elsif (@res == 1 && UNIVERSAL::can($res[0], '()')) { + } elsif (@res == 1 && !$ISEVAL && $STRINGIFY + && UNIVERSAL::can($res[0], '()')) { # overloaded? $res = $res[0]; } elsif (!$ISEVAL && $COLUMNATE && @res > 1 && !grep ref, @res) { @@ -823,6 +852,7 @@ BEGIN { $WANTARRAY = '@'; $PRINTER = 'dumper'; $COLUMNATE = 1; + $STRINGIFY = 1; } =item C -- Print the REPL prompt. @@ -1010,6 +1040,8 @@ sub define_shortcuts 'freload MODULE', 'Reload MODULE and all its dependencies.'; define_shortcut time => \&Sepia::repl_time, 'time [0|1]', 'Print timing information for each command.'; + define_shortcut lsmod => \&Sepia::repl_lsmod, + 'lsmod [PATTERN]', 'List loaded modules matching PATTERN.'; } =item C @@ -1575,6 +1607,30 @@ sub repl_reload } } +sub repl_lsmod +{ + chomp (my $pat = shift); + $pat ||= '.'; + $pat = qr/$pat/; + my $first = 1; + my $fmt = "%-20s%8s %s\n"; + for (sort keys %INC) { + my $file = $_; + s!/!::!g; + s/\.p[lm]$//; + next if /^::/ || !/$pat/; + if ($first) { + printf $fmt, qw(Module Version File); + printf $fmt, qw(------ ------- ----); + $first = 0; + } + printf $fmt, $_, (UNIVERSAL::VERSION($_)||'???'), $INC{$file}; + } + if ($first) { + print "No modules found.\n"; + } +} + =item C Collect C<$warning> for later printing. @@ -1688,9 +1744,9 @@ sub repl my $in; my $buf = ''; - my $sigged = 0; + $SIGGED = 0; - my $nextrepl = sub { $sigged = 1; }; + my $nextrepl = sub { $SIGGED++; }; local (@_, $_); local *CORE::GLOBAL::die = \&Sepia::Debug::die; @@ -1699,9 +1755,9 @@ sub repl local @SIG{@sigs}; $SIG{$_} = $nextrepl for @sigs; repl: while (defined(my $in = $READLINE->())) { - if ($sigged) { + if ($SIGGED) { $buf = ''; - $sigged = 0; + $SIGGED = 0; print "\n"; next repl; } @@ -1929,6 +1985,25 @@ sub apropos_module sort keys %ret; } +sub requires +{ + my $mod = shift; + my @q = $REQUIRES{$mod}; + my @done; + while (@q) { + my $m = shift @q; + push @done, $m; + push @q, @{$REQUIRES{$m}}; + } + @done; +} + +sub users +{ + my $mod = shift; + @{$REQUIRED_BY{$mod}} +} + 1; __END__ diff --git a/package.sh b/package.sh index 5c06569..ec794d9 100755 --- a/package.sh +++ b/package.sh @@ -1,7 +1,9 @@ #!/bin/sh -makeinfo --no-split --no-headers --html sepia.texi -o Sepia.html # cat MANIFEST.in > MANIFEST # ls doc/*.html >> MANIFEST # perl Makefile.PL && make && make test && make dist perl Makefile.PL && make && make dist +perl -Mblib -MSepia -i -pe 's/^(\@set VERSION ).*/$1$Sepia::VERSION/' sepia.texi +makeinfo sepia.texi -o Sepia.info +makeinfo --no-split --no-headers --html sepia.texi -o Sepia.html diff --git a/sepia.el b/sepia.el index 8f74c03..215e06a 100644 --- a/sepia.el +++ b/sepia.el @@ -243,7 +243,8 @@ might want to bind your keys, which works best when bound to (interactive (list (sepia-interactive-arg 'module))) (let ((wc (current-window-configuration)) (old-pd (symbol-function 'w3m-about-perldoc)) - (old-pdb (symbol-function 'w3m-about-perldoc-buffer))) + (old-pdb (symbol-function 'w3m-about-perldoc-buffer)) + buf) (condition-case stuff (flet ((w3m-about-perldoc (&rest args) (let ((res (apply old-pd args))) @@ -251,8 +252,11 @@ might want to bind your keys, which works best when bound to (w3m-about-perldoc-buffer (&rest args) (let ((res (apply old-pdb args))) (or res (error "lose: %s" args))))) - (funcall (if (featurep 'w3m) 'w3m-perldoc 'cperl-perldoc) name)) - (error (set-window-configuration wc))))) + (funcall (if (featurep 'w3m) 'w3m-perldoc 'cperl-perldoc) name) + (setq buf (current-buffer))) + (error (set-window-configuration wc))) + (set-window-configuration wc) + (pop-to-buffer buf t))) (defun sepia-view-pod () "View POD for the current buffer." @@ -1467,8 +1471,14 @@ When called interactively, the current buffer's (defvar sepia-doc-map (make-hash-table :test #'equal)) (defvar sepia-var-doc-map (make-hash-table :test #'equal)) (defvar sepia-module-doc-map (make-hash-table :test #'equal)) +(defvar sepia-skip-doc-scan nil) (defun sepia-doc-scan-buffer () + ;; too many confusing things in perldiag, so just give up. + (when (or sepia-skip-doc-scan + (and (buffer-file-name) + (string-match "perldiag\\.pod$" (buffer-file-name)))) + (return nil)) (save-excursion (goto-char (point-min)) (loop @@ -1511,7 +1521,7 @@ When called interactively, the current buffer's (or (and (equal short (match-string 1 short)) longdoc) short))) ;; e.g. "C<$result = foo $args...>" - ((string-match "=\\s *\\([A-Za-z0-9_:]+\\)" short) + ((string-match "^[%@$*][A-Za-z0-9_:]+\\s *=\\s *\\([A-Za-z0-9_:]+\\)" short) (list 'function (match-string-no-properties 1 short) (or (and (equal short (match-string 1 short)) longdoc) short))) @@ -1530,7 +1540,10 @@ When called interactively, the current buffer's "Update documentation for a file. This documentation, taken from \"=item\" entries in the POD, is -used for eldoc feedback." +used for eldoc feedback. Set the file variable +`sepia-skip-doc-scan' to non-nil to skip scanning this buffer. +This can be used to avoid generating bogus documentation from +files like perldiag.pod." (interactive) (let ((pack (ifa (sepia-buffer-package) (concat it "::") ""))) (dolist (x (sepia-doc-scan-buffer)) @@ -1621,7 +1634,10 @@ calling `cperl-describe-perl-symbol'." ""))) (defun sepia-install-eldoc () - "Install Sepia hooks for eldoc support." + "Install Sepia hooks for eldoc support. + +This automatically disables `cperl-lazy-installed', the +`cperl-mode' reimplementation of eldoc." (interactive) (require 'eldoc) (set-variable 'eldoc-documentation-function 'sepia-symbol-info t) @@ -1696,9 +1712,73 @@ calling `cperl-describe-perl-symbol'." (defun sepia-find-loaded-modules () (interactive) - "Find all files loaded by the currently-running Perl." + "Visit all source files loaded by the currently-running Perl. + +Currently, this means any value of %INC matching /.p[lm]$/." (dolist (file (sepia-eval "values %INC" 'list-context)) - (find-file-noselect file t))) + (when (string-match "\\.p[lm]$" file) + (find-file-noselect file t)))) + +(defun sepia-dired-package (package) + (interactive "sPackage: ") + "Browse files installed by `package'. + +Create a `dired-mode' buffer listing all flies installed by `package'." + ;; XXX group by common prefix and use /^ DIRECTORY:$/ format + (let ((ls (sort #'string< + (sepia-call "Sepia::file_list" 'list-context package))) + pfx + maxlen) + (setq maxlen (apply #'max (mapcar #'length ls))) + (with-current-buffer (get-buffer-create (format "*Package %s*" package)) + (let ((inhibit-read-only t) + marker) + ;; Start with a clean slate + (erase-buffer) + (setq marker (point-min-marker)) + (set (make-local-variable 'dired-subdir-alist) nil) + ;; Build up the contents + (while ls + ;; Find a decent prefix + (setq pfx (try-completion "" ls)) + (unless (file-exists-p pfx) + (string-match "^\\(.*/\\)" pfx) + (setq pfx (match-string 1 pfx))) + ;; If we found a lousy prefix, chew off the first few paths and + ;; try again. XXX not done. + (insert (format " %s:\n" pfx)) + (setq default-directory pfx) + (apply 'call-process "/bin/ls" nil (current-buffer) t + (cons "-lR" (mapcar + (lambda (x) + (replace-regexp-in-string + (concat pfx "?") "" x)) + ls))) + (push `((,default-directory . ,marker)) dired-subdir-alist) + (setq ls nil)) + (dired-mode pfx) + (pop-to-buffer (current-buffer)))))) + +;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;; +;;; Fight CPerl a bit -- it can be opinionated + +(defadvice cperl-imenu--create-perl-index (after simplify compile activate) + "Make cperl's imenu index simpler." + (flet ((annoying (x) + (dolist (y '("Rescan" "^\\+Unsorted" "^\\+Packages")) + (when (string-match y (car x)) + (return-from annoying t))) + nil)) + (setq ad-return-value (remove-if #'annoying ad-return-value)))) + +;; (defun sepia-view-mode-hook () +;; "Let backspace scroll again. + +;; XXX Unused, yet." +;; (local-unset-key (kbd ""))) + +;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;; +;;; __DATA__ (defun sepia-init-perl-builtins () (setq sepia-perl-builtins (make-hash-table :test #'equal)) diff --git a/sepia.info b/sepia.info index c0dead5..9d044ef 100644 --- a/sepia.info +++ b/sepia.info @@ -1,12 +1,15 @@ -This is sepia.info, produced by makeinfo version 4.8 from sepia.texi. +This is Sepia.info, produced by makeinfo version 4.8 from sepia.texi. INFO-DIR-SECTION Emacs START-INFO-DIR-ENTRY * Sepia: (sepia). Simple Emacs Perl Integration. END-INFO-DIR-ENTRY + Copyright (C) 2005-2010 Sean O'Rourke. All rights reserved, some +wrongs reversed. This module is distributed under the same terms as +Perl.  -File: sepia.info, Node: Top, Next: Introduction, Prev: (dir), Up: (dir) +File: Sepia.info, Node: Top, Next: Introduction, Prev: (dir), Up: (dir) SEPIA ***** @@ -22,12 +25,13 @@ navigation and interactive evaluation. * CPAN browsing:: * Customization:: * Internals:: +* FAQ:: * Credits:: * Function Index:: * Variable Index::  -File: sepia.info, Node: Introduction, Next: Editing, Prev: Top, Up: Top +File: Sepia.info, Node: Introduction, Next: Editing, Prev: Top, Up: Top 1 Introduction ************** @@ -44,7 +48,7 @@ other languages, including Lisp, Python, and Emacs Lisp. * Related Work::  -File: sepia.info, Node: Getting Started, Next: Philosophy, Prev: Introduction, Up: Introduction +File: Sepia.info, Node: Getting Started, Next: Philosophy, Prev: Introduction, Up: Introduction 1.1 Getting Started =================== @@ -62,7 +66,7 @@ following lines to `~/.emacs': Then to bring up the interactive Perl prompt, type `M-x sepia-repl'.  -File: sepia.info, Node: Philosophy, Next: Related Work, Prev: Getting Started, Up: Introduction +File: Sepia.info, Node: Philosophy, Next: Related Work, Prev: Getting Started, Up: Introduction 1.2 Philosophy ============== @@ -85,10 +89,10 @@ and file trees. Rather than supporting interactive evaluation of small pieces of code, they perform background semantic checking on whole projects and highlight errors. Rather than allowing minor customizations to grow organically into features, they support limited -configuration files and baroque plug-in APIs. Sepia tries to adhere to -the apparent Emacs philosophy that rich semantic information should be -unobtrusive, and that the best way to build working code is to start by -experimenting with small pieces. +configuration files and baroque plug-in APIs(1). Sepia tries to adhere +to the apparent Emacs philosophy that rich semantic information should +be unobtrusive, and that the best way to build working code is to start +by experimenting with small pieces. Language support packages for Emacs vary widely in the degree to which they make use of or replace existing Emacs features. Minimal @@ -116,8 +120,15 @@ strange for someone used Perl's typical mix of one-liners and edit-save-run, but once you are accustomed to it, you may find it very effective. + ---------- Footnotes ---------- + + (1) In my brief experience with Visual Studio, I was struck by the +fact that I saw several toolbars, a couple of navigation windows, and a +tiny view of the actual code. Sometimes a tooltip would obscure part +of that tiny window. +  -File: sepia.info, Node: Related Work, Prev: Philosophy, Up: Introduction +File: Sepia.info, Node: Related Work, Prev: Philosophy, Up: Introduction 1.3 Related Work ================ @@ -150,7 +161,7 @@ them regularly, these impressions should be taken with a grain of salt.  -File: sepia.info, Node: Editing, Next: Interactive Perl, Prev: Introduction, Up: Top +File: Sepia.info, Node: Editing, Next: Interactive Perl, Prev: Introduction, Up: Top 2 Editing ********* @@ -169,7 +180,7 @@ completion. * Other commands::  -File: sepia.info, Node: Completion, Next: Navigation, Prev: Editing, Up: Editing +File: Sepia.info, Node: Completion, Next: Navigation, Prev: Editing, Up: Editing 2.1 Completion ============== @@ -218,7 +229,7 @@ completion is not currently supported for lexicals._  -File: sepia.info, Node: Navigation, Next: Documentation, Prev: Completion, Up: Editing +File: Sepia.info, Node: Navigation, Next: Documentation, Prev: Completion, Up: Editing 2.2 Navigation ============== @@ -320,7 +331,7 @@ not fit into either of the above categories.  -File: sepia.info, Node: Documentation, Next: Other commands, Prev: Navigation, Up: Editing +File: Sepia.info, Node: Documentation, Next: Other commands, Prev: Navigation, Up: Editing 2.3 Documentation ================= @@ -361,7 +372,7 @@ This is intended to give the programmer a sense of when he is creating external dependencies.  -File: sepia.info, Node: Other commands, Prev: Documentation, Up: Editing +File: Sepia.info, Node: Other commands, Prev: Documentation, Up: Editing 2.4 Other commands ================== @@ -372,7 +383,7 @@ File: sepia.info, Node: Other commands, Prev: Documentation, Up: Editing is only a thin wrapper around `query-replace'.  -File: sepia.info, Node: Interactive Perl, Next: CPAN browsing, Prev: Editing, Up: Top +File: Sepia.info, Node: Interactive Perl, Next: CPAN browsing, Prev: Editing, Up: Top 3 Interactive Perl ****************** @@ -388,6 +399,10 @@ in Sepia mode, in the REPL performs partial-word completion with code in Perl, and commands to process buffer text using the inferior process. + Finally, Sepia comes with the `sepl' program, a standalone REPL that +can be run from the command-line, and provides many features of the +Emacs-based REPL. + * Menu: * Shortcuts:: @@ -397,7 +412,7 @@ process. * Scratchpad::  -File: sepia.info, Node: Shortcuts, Next: Debugger, Prev: Interactive Perl, Up: Interactive Perl +File: Sepia.info, Node: Shortcuts, Next: Debugger, Prev: Interactive Perl, Up: Interactive Perl 3.1 Shortcuts ============= @@ -426,8 +441,11 @@ additional shortcuts (*Note Debugger::.). `format TYPE' Set the output format to TYPE, either "dumper" (using - `Data::Dumper'), "dump" (`Data::Dump'), "yaml" (`YAML'), or - "plain" (stringification). Default: "dumper". + `Data::Dumper'), "dump" (`Data::Dump'), "yaml" (`YAML'), "peek" + (`Devel::Peek'), or "plain" (stringification). Default: "dumper". + + Note that this setting is independent of `$COLUMNATE' and + `$STRINGIFY'. `help' Display a list of shortcuts. @@ -499,8 +517,8 @@ additional shortcuts (*Note Debugger::.). remove built-in shortcuts. `wantarray [VAL]' - Set the evaluation context to VAL, or toggle between scalar and - array context. + Set the evaluation context to VAL: `@' means array, `$' means + scalar, and anything else means void. `who PACKAGE [REGEXP]' `who [REGEXP]' @@ -509,7 +527,7 @@ additional shortcuts (*Note Debugger::.).  -File: sepia.info, Node: Debugger, Next: Evaluation, Prev: Shortcuts, Up: Interactive Perl +File: Sepia.info, Node: Debugger, Next: Evaluation, Prev: Shortcuts, Up: Interactive Perl 3.2 Debugger ============ @@ -561,7 +579,7 @@ and modify lexical variables.  -File: sepia.info, Node: Evaluation, Next: Mutilation, Prev: Debugger, Up: Interactive Perl +File: Sepia.info, Node: Evaluation, Next: Mutilation, Prev: Debugger, Up: Interactive Perl 3.3 Evaluation ============== @@ -592,7 +610,7 @@ process has already been started by calling `sepia-repl'.  -File: sepia.info, Node: Mutilation, Next: Scratchpad, Prev: Evaluation, Up: Interactive Perl +File: Sepia.info, Node: Mutilation, Next: Scratchpad, Prev: Evaluation, Up: Interactive Perl 3.4 Mutilation ============== @@ -617,7 +635,7 @@ functions and variables in the interactive session are available.  -File: sepia.info, Node: Scratchpad, Prev: Mutilation, Up: Interactive Perl +File: Sepia.info, Node: Scratchpad, Prev: Mutilation, Up: Interactive Perl 3.5 Scratchpad ============== @@ -629,7 +647,7 @@ except evaluates the current line and prints the result on the next line.  -File: sepia.info, Node: CPAN browsing, Next: Customization, Prev: Interactive Perl, Up: Top +File: Sepia.info, Node: CPAN browsing, Next: Customization, Prev: Interactive Perl, Up: Top 4 CPAN browsing *************** @@ -666,7 +684,7 @@ following commands are available:  -File: sepia.info, Node: Customization, Next: Internals, Prev: CPAN browsing, Up: Top +File: Sepia.info, Node: Customization, Next: Internals, Prev: CPAN browsing, Up: Top 5 Customization *************** @@ -680,7 +698,7 @@ the user-accessible configuration is in the latter. * Perl Variables::  -File: sepia.info, Node: Emacs Variables, Next: Perl Variables, Prev: Customization, Up: Customization +File: Sepia.info, Node: Emacs Variables, Next: Perl Variables, Prev: Customization, Up: Customization 5.1 Emacs Variables =================== @@ -743,14 +761,15 @@ configuration can be done with `sepia-repl-mode-hook'.  -File: sepia.info, Node: Perl Variables, Prev: Emacs Variables, Up: Customization +File: Sepia.info, Node: Perl Variables, Prev: Emacs Variables, Up: Customization 5.2 Perl Variables ================== When Sepia starts up, it evaluates the Perl script in `~/.sepiarc'. -The following variables in the Sepia package control various aspects of -interactive evaluation. + + The following variables in the Sepia package control various aspects +of interactive evaluation. `$PACKAGE' The package in which user input is evaluated, determined @@ -765,6 +784,10 @@ interactive evaluation. If true, columnate simple arrays independent of the value of `$PRINTER'. Default: true. +`$STRINGIFY' + If true, stringify objects that overload the operation independent + of the value of `$PRINTER'. Default: true. + `$PS1' The trailing end of the prompt string, which should end with "> ". Default: `"> "'. @@ -778,8 +801,8 @@ interactive evaluation. Sepia debugger. Default: false. `$WANTARRAY' - If true, evaluate interactive expressions in list context. - Default: true. + If `@', evaluate interactive expressions in list context, if `$', + scalar, otherwise, void. Default: `@'. Additional REPL shortcuts can be defined with @@ -792,7 +815,7 @@ interactive evaluation. details, see the code in `Sepia.pm'.  -File: sepia.info, Node: Internals, Next: Credits, Prev: Customization, Up: Top +File: Sepia.info, Node: Internals, Next: FAQ, Prev: Customization, Up: Top 6 Internals *********** @@ -803,7 +826,31 @@ developer documentation, please see the POD for `Sepia' and `Sepia::Xref', and the doc-strings in `sepia.el'.  -File: sepia.info, Node: Credits, Next: Function Index, Prev: Internals, Up: Top +File: Sepia.info, Node: FAQ, Next: Credits, Prev: Internals, Up: Top + +7 FAQ +***** + +Can I use `Sepia' outside of Emacs? + Sepia comes with the `sepl' program, a command-line REPL using the + `Sepia::Readline' module, that provides many features of the + Emacs-based REPL. It could be improved, though - patches welcome! + +Why is the documentation in TeXInfo format?! + TeXInfo is the worst form of documentation, except for all the + others. TeX and LaTeX produce beautiful printed output, and Info + is the best way to view documentation in Emacs for things that are + not themselves part of Emacs (i.e. "can have docstrings"). + + It's awful to edit, being both verbose and redundant - just look at + AUCTeX's `texinfo-every-node-update' for desperate placation of the + suck, then try to figure out what's wrong when `makeinfo' complains + about `texinfo-every-node-update''s output - but it's what we + have. At least it sucks less than `DocBook', raw HTML, or `troff'. + + + +File: Sepia.info, Node: Credits, Next: Function Index, Prev: FAQ, Up: Top Credits ******* @@ -824,7 +871,7 @@ Free Software  -File: sepia.info, Node: Function Index, Next: Variable Index, Prev: Credits, Up: Top +File: Sepia.info, Node: Function Index, Next: Variable Index, Prev: Credits, Up: Top Function Index ************** @@ -871,7 +918,7 @@ Function Index * sepia-view-pod: Documentation. (line 16)  -File: sepia.info, Node: Variable Index, Prev: Function Index, Up: Top +File: Sepia.info, Node: Variable Index, Prev: Function Index, Up: Top Variable Index ************** @@ -893,29 +940,31 @@ Variable Index  Tag Table: -Node: Top187 -Node: Introduction549 -Node: Getting Started987 -Node: Philosophy1612 -Node: Related Work4639 -Node: Editing5805 -Node: Completion6286 -Node: Navigation8363 -Node: Documentation11921 -Node: Other commands13491 -Node: Interactive Perl13826 -Node: Shortcuts14563 -Node: Debugger18164 -Node: Evaluation19708 -Node: Mutilation20684 -Node: Scratchpad21636 -Node: CPAN browsing22041 -Node: Customization23035 -Node: Emacs Variables23333 -Node: Perl Variables25828 -Node: Internals27250 -Node: Credits27610 -Node: Function Index28068 -Node: Variable Index30914 +Node: Top331 +Node: Introduction701 +Node: Getting Started1139 +Node: Philosophy1764 +Ref: Philosophy-Footnote-14830 +Node: Related Work5064 +Node: Editing6230 +Node: Completion6711 +Node: Navigation8788 +Node: Documentation12346 +Node: Other commands13916 +Node: Interactive Perl14251 +Node: Shortcuts15147 +Node: Debugger18876 +Node: Evaluation20420 +Node: Mutilation21396 +Node: Scratchpad22348 +Node: CPAN browsing22753 +Node: Customization23747 +Node: Emacs Variables24045 +Node: Perl Variables26540 +Node: Internals28133 +Node: FAQ28489 +Node: Credits29507 +Node: Function Index29959 +Node: Variable Index32805  End Tag Table diff --git a/sepia.texi b/sepia.texi index 39c01f9..3fa6719 100644 --- a/sepia.texi +++ b/sepia.texi @@ -6,6 +6,11 @@ @direntry * Sepia: (sepia). Simple Emacs Perl Integration. @end direntry +@copying +Copyright @copyright{} 2005-2010 Sean O'Rourke. All rights reserved, +some wrongs reversed. This module is distributed under the same terms +as Perl. +@end copying @c %**end of header @titlepage @@ -41,15 +46,16 @@ Sepia is a set of Perl development tools for Emacs supporting code navigation and interactive evaluation. @menu -* Introduction:: -* Editing:: -* Interactive Perl:: -* CPAN browsing:: -* Customization:: -* Internals:: +* Introduction:: +* Editing:: +* Interactive Perl:: +* CPAN browsing:: +* Customization:: +* Internals:: +* FAQ:: * Credits:: -* Function Index:: -* Variable Index:: +* Function Index:: +* Variable Index:: @end menu @c ============================================================ @@ -106,10 +112,13 @@ class and file trees. Rather than supporting interactive evaluation of small pieces of code, they perform background semantic checking on whole projects and highlight errors. Rather than allowing minor customizations to grow organically into features, they support limited -configuration files and baroque plug-in APIs. Sepia tries to adhere to -the apparent Emacs philosophy that rich semantic information should be -unobtrusive, and that the best way to build working code is to start -by experimenting with small pieces. +configuration files and baroque plug-in APIs@footnote{In my brief +experience with Visual Studio, I was struck by the fact that I saw +several toolbars, a couple of navigation windows, and a tiny view of the +actual code. Sometimes a tooltip would obscure part of that tiny +window.}. Sepia tries to adhere to the apparent Emacs philosophy that +rich semantic information should be unobtrusive, and that the best way +to build working code is to start by experimenting with small pieces. Language support packages for Emacs vary widely in the degree to which they make use of or replace existing Emacs features. Minimal modes @@ -494,7 +503,12 @@ passed the raw command-line text as its first argument. @item format @var{type} Set the output format to @var{type}, either ``dumper'' (using @code{Data::Dumper}), ``dump'' (@code{Data::Dump}), ``yaml'' -(@code{YAML}), or ``plain'' (stringification). Default: ``dumper''. +(@code{YAML}), ``peek'' (@code{Devel::Peek}), ``dumpvar'' +(@code{dumpvar.pl}, somewhat rough), or ``plain'' (stringification). +Default: ``dumper''. + +Note that this setting is independent of @code{$COLUMNATE} and +@code{$STRINGIFY}. @item help Display a list of shortcuts. @@ -506,6 +520,9 @@ created by @kbd{save}. @item lsbreak List breakpoints. +@item lsmod [@var{pattern}] +List currently-loaded modules matching optional @var{pattern}. + @item methods @var{name} [@var{regexp}] Display a list of functions defined in package @var{name} and its @code{ISA}-ancestors matching optional pattern @var{regexp}. @@ -838,6 +855,10 @@ The function called to format interactive output, normally set with the If true, columnate simple arrays independent of the value of @code{$PRINTER}. Default: true. +@item $STRINGIFY +If true, stringify objects that overload the operation independent of +the value of @code{$PRINTER}. Default: true. + @item $PS1 The trailing end of the prompt string, which should end with ``> ''. Default: @code{"> "}. @@ -868,7 +889,7 @@ defines a shortcut ``time'' that displays the current time. For details, see the code in @file{Sepia.pm}. @c ============================================================ -@node Internals, Credits, Customization, Top +@node Internals, FAQ, Customization, Top @chapter Internals Many things remain unexplained except by the code itself, and some @@ -876,7 +897,31 @@ details mentioned above should probably be given less prominence. For developer documentation, please see the POD for @code{Sepia} and @code{Sepia::Xref}, and the doc-strings in @file{sepia.el}. -@node Credits, Function Index, Internals, Top +@node FAQ, Credits, Internals, Top +@chapter FAQ + +@table @asis +@item Can I use @code{Sepia} outside of Emacs? +Sepia comes with the @file{sepl} program, a command-line REPL using the +@code{Sepia::Readline} module, that provides many features of the +Emacs-based REPL. It could be improved, though -- patches welcome! + +@item Why is the documentation in TeXInfo format?! +TeXInfo is the worst form of documentation, except for all the others. +TeX and LaTeX produce beautiful printed output, and Info is the best way +to view documentation in Emacs for things that are not themselves part +of Emacs (i.e. ``can have docstrings''). + +It's awful to edit, being both verbose and redundant -- just look at +AUCTeX's @code{texinfo-every-node-update} for desperate placation of the +suck, then try to figure out what's wrong when @file{makeinfo} complains +about @code{texinfo-every-node-update}'s output -- but it's what we +have. At least it sucks less than @code{DocBook}, raw HTML, or +@file{troff}. + +@end table + +@node Credits, Function Index, FAQ, Top @unnumbered Credits @table @asis -- 2.11.4.GIT