NAME

Emacs::Lisp - Support for Perl embedded in GNU Emacs

SYNOPSIS

In Emacs

M-x load-library RET perl RET
M-x perl-eval-expression RET 2+2 RET

In Perl

  use Emacs::Lisp;

  &switch_to_buffer('*scratch*');
  &insert("Hello, world!\n");

  setq { $cperl_font_lock = t };

  &add_hook(\*find_file_hooks,
	    sub { &message("found a file!") });

  use Emacs::Lisp qw($emacs_version $perlmacs_version);
  save_excursion {
    &set_buffer(&get_buffer_create("whatever"));
    &insert("This is Emacs version $emacs_version,\n");
    &insert("Perlmacs version $perlmacs_version.\n");
    &insert("Emacs::Lisp version is $Emacs::Lisp::VERSION.\n");
  };

DESCRIPTION

Until now, you could customize your Emacs environment using Lisp. Now you can use Perl, too. This module allows Perl code to call functions and access variables of Lisp. It also maps some Perl syntax into Lisp semantics.

You still need to learn some Lisp in order to understand The Elisp Manual, which you will need if you wish to learn about the details of Emacs programming. Hopefully, this situation will be cured by the appearance of well-documented Perl modules that give everything in Emacs a nice, object-oriented wrapping.

EMACS SUPPORT FOR PERL

A patched emacs program with embedded Perl can compile and evaluate Perl code via Emacs Lisp or the command line, independently of the Emacs::Lisp module.

Functions

The Perlmacs patch builds some Perl-related functions into Lisp. Use C-h f function-name RET within Emacs for documentation on these.

perl-eval		EXPRESSION &optional CONTEXT
perl-call		CODEREF &optional CONTEXT &rest ARGS
make-perl-interpreter	&rest ARGV
perl-run		&optional INTERPRETER
perl-destruct		&optional INTERPRETER

You need to do M-x load-library RET perl RET (or hack your ~/.emacs) to get the following functions.

perl-eval-expression	EXPRESSION
perl-eval-region	START END
perl-eval-buffer
perl-load-file	NAME

Note that the exact meaning of perl-load-file is a topic of research and may change.

Data Conversions

When data is passed between Lisp and Perl within Emacs, some basic principles apply. These are goals that may never be entirely met, due to the differences between Perl and Lisp.

Whatever Perl gives to Lisp should get dereferenced once.

A Perl reference gets converted into a Lisp reference to the thing referenced, not a Lisp reference to the Perl reference. (I find this to be intuitively correct behavior.)
Converting a non-dereferenceable value requires some kind of primitive conversion.

For example, Lisp integers, floats, and strings all become Perl scalars. A scalar (other than a reference) converted to Lisp will become either an integer, a float, or a string. Glob references in Perl become symbols in Lisp (subject to the usual underscore-to-hyphen translation).
Lisp's `nil' is equivalent to Perl's `undef' or `()'.

In Lisp, nil is really a symbol. However, it is typically used as the boolean value false. Perl's equivalent of symbols (glob references) evaluate to true in boolean contexts. Converting nil to anything other than undef would be disastrous for programmers' mental health!
Generally, converted values can be converted back to Perl more or less unchanged.

But not always. For example, \*nil would become undef.
Lisp objects which are not converted Perl stuff and have no natural counterpart become `Emacs::Lisp::Object' blessed references.

These hold the actual Lisp data and a means of protecting it from garbage collection. An Emacs::Lisp::Object reference converted back to Lisp is the Lisp object.

Scripts

Emacs with embedded Perl can run Perl programs. If the first command-line argument is --perl, the rest will be parsed as if by the perl program.

When you use Emacs::Lisp in a script started this way, a Perl sub named Emacs::main may be used to invoke the Emacs editor. This makes it possible to put customization code, which would normally appear in ~/.emacs, into a "Perlmacs script". For example, this startup code

(setq
 user-mail-address "gnaeus@perl.moc"
 mail-self-blind t
 mail-yank-prefix "> "
 )

(put 'eval-expression 'disabled nil)

(global-font-lock-mode 1 t)
(set-face-background 'highlight "maroon")
(set-face-background 'region "Sienna")

could be placed in a file with the following contents:

#! /usr/local/bin/emacs --perl

use Emacs::Lisp;

setq {
  $user_mail_address = 'gnaeus@perl.moc';
  $mail_self_blind = t;
  $mail_yank_prefix = '> ';
  $eval_expression{\*disabled} = undef;
};

&global_font_lock_mode(1, t);
&set_face_background(\*highlight, "maroon");
&set_face_background(\*region, "Sienna");

exit Emacs::main($0, "-q", @ARGV);

When you wanted to run Emacs, you would invoke this program.

The arguments to Emacs::main correspond to the argv of the main function in a C program. The first argument should be the program's invocation name, as in this example. -q inhibits running ~/.emacs (which is what we're trying to get away from, after all).

PERL SUPPORT FOR LISP

The Emacs::Lisp module allows Perl programs to invoke Lisp functions and handle Lisp data using Perl's syntax.

You don't have to do any work, other than use Emacs::Lisp, to make subs call their Lisp counterpart. However, tying Lisp variables to Perl variables is not quite so automatic. In all cases, hyphens appearing in Lisp names are translated to underscores in Perl, and vice versa.

Functions

This code calls the hypothetical Lisp function foo-bar with arguments 4 and t.

&foo_bar(4, t);

The Lisp syntax for the same call would be

(foo-bar 4 t)

The ampersand (&) is only really needed for calling Lisp functions such as read, eval, and print, which are Perl keywords. But using it is a good habit.

Symbols

Many Lisp functions take arguments that may be, or are required to be, symbols. Lisp programs typically use the quote operator to specify a symbol. For example, this Lisp code refers to the beep symbol:

(run-at-time nil 1 'beep)

Perlmacs uses glob references of package main to specify symbols. A literal globref begins with a backslash followed by an asterisk, so the last example would be written as

&run_at_time(undef, 1, \*beep);

in Perl. (You may want to do &cancel_function_timers(\*beep) soon after trying this.)

Note that only globs from package main get converted to symbols, so code that is compiled in another package must use the form \*::sym rather than \*sym.

Variables

In Lisp, variables play a role akin to that of Perl scalars. A variable may hold a number, a string, or a reference to any type of complex Lisp data structure. (They are not called references in Lisp, but rather "objects".)

You can create a Perl alias for any reasonably named Lisp variable by saying use Emacs::Lisp qw($varname). Thereafter, assignment to $varname will update the Lisp value. Changes made to the variable in Lisp will be reflected in $varname when used in Perl expressions.

This example saves and replaces the value of the Lisp variable inhibit-eol-conversion:

use Emacs::Lisp qw($inhibit_eol_conversion);
$old_val = $inhibit_eol_conversion;
$inhibit_eol_conversion = 1;

This sort of thing could be accomplished in Lisp as follows:

(setq old-val inhibit-eol-conversion)
(setq inhibit-eol-conversion 1)

Property Lists

Lisp symbols all have an associated object called a plist (for "property list"). Although it is actually an object just like any other, the plist is typically used in a way vaguely resembling Perl hashes.

Note that a plist is different from a Perl hash. Lookups are not based on string equality as with Perl, but rather on Lisp object equality (of the eq variety, I believe). For this reason, it is best to stick to the Lisp convention of using only symbols as keys. (See "Symbols".)

Emacs::Lisp provides a shorthand notation for getting and setting plist elements. If you say use Emacs::Lisp qw(%any_name), then subsequent access to the hash elements of %any_name will really get or set the corresponding plist entries (i.e., properties of the Lisp symbol any-name).

For example, the following Perl and Lisp fragments are more or less equivalent:

# Perl fragment
use Emacs::Lisp qw(%booboo %upcase_region);
$booboo{\*error_conditions} = &list(\*booboo, \*error);
$can_upcase = ! $upcase_region{\*disabled};

; Lisp fragment
(put 'booboo 'error-conditions '(booboo error))
(setq can-upcase (not (get 'upcase-region 'disabled)))

Special Forms

So-called "special forms" in Lisp, such as setq and defun, do not work the same way functions do. Some of them are equivalent to Perl operators, such as if and and. Others have meanings peculiar to Lisp.

A few special forms are implemented in Emacs::Lisp. They are listed below. If you try to call one that's not been implemented, you will get an error message, which may propose an alternative.

defun SYMBOL,DOCSTRING,SPEC,CODE

defun SYMBOL,DOCSTRING,CODE

defun SYMBOL,SPEC,CODE

defun SYMBOL,CODE

Make CODE callable as the Lisp function SYMBOL. This is Lisp's version of Perl's sub keyword. A function defined in this way becomes visible to Lisp code.

This is primarily useful for defining Emacs commands. Commands are functions that the user can invoke by typing M-x <function-name>. A command may be bound to a key or sequence of keystrokes. See the Emacs documentation for specifics.

As in Emacs Lisp, when defining a command, you must specify the interactive nature of the command. There are various codes to indicate that the command acts on the current region, a file name to be read from the minibuffer, etc. Please see The Elisp Manual for details. Emacs::Lisp' defun uses a value returned by interactive as the SPEC for this purpose. See "interactive".

This example creates a command, reverse-region-words, that replaces a region of text with the same text after reversing the order of words. To be user-friendly, we'll provide a documentation string, which will be accessible through the Emacs help system (C-h f).

  use Emacs::Lisp;
  defun (\*reverse_region_words,
	 "Reverse the order of the words in the region.",
	 interactive("r"),
	 sub {
	     my ($start, $end) = @_;
	     my $text = &buffer_substring($start, $end);
	     $text = join('', reverse split (/(\s+)/, $text));
	     &delete_region($start, $end);
	     &insert($text);
	 });

interactive SPEC

interactive

Used to generate the third (or, in the absence of a doc string, second) argument to defun, which see. This determines how a command's arguments are obtained.

SPEC may be a string as described in The Elisp Manual or a reference to code which returns the argument list.

save_excursion BLOCK

Execute BLOCK within a Lisp save-excursion construct. This restores the current buffer and other settings to their original values after the code has completed.

Please read The Elisp Manual for details.

setq BLOCK

BLOCK is searched for assignments (at top level) of the form

$var = EXPR;

where $var is a scalar variable or hash element. Every such variable is imported from the Emacs::Lisp module, as if you had said use Emacs::Lisp qw($var).

Afterwards, BLOCK is executed. Thus, this code

use Emacs::Lisp;
setq {
  $A = 2*$foo[5];
  $B{\*foo} = "more than $A";
};

would have exactly the same effect as

use Emacs::Lisp qw(:DEFAULT $A %B);
$A = 2*$foo[5];
$B{\*foo} = "more than $A";

The following, which does not tie or import any symbols, has the same effect on Lisp as the above:

use Emacs::Lisp ();
&Emacs::Lisp::set( \*A, 2*$foo[5] );
&Emacs::Lisp::put( \*B, \*foo, "more than "
  . &Emacs::Lisp::symbol_value( \*A ));

BUGS

Crashes during complex jump operations.

For example, both of these generate a core dump on my system:
```
emacs --perl -MEmacs::Lisp -e 'perl_eval("goto foo");foo:'

(defun throwfoo () (throw 'foo t))
(defun catchfoo () (catch 'foo (perl-eval "&throwfoo()")))
(perl-eval "&catchfoo()")
```
I think this is fixable, it just hasn't been fixed yet. (As of this writing, Perlmacs is an ALPHA version. This is the major issue preventing me from releasing either Perlmacs or Emacs::Lisp as BETA.)
Memory leaks and other problems with `Emacs::main'.

The Emacs::main sub may open an X display and not close it. That is the most obvious of many problems with Emacs::main.

For best results, the value returned by Emacs::main should be passed to Perl's exit soon, as in this code:
```
exit (Emacs::main($0, @args));
```
Perl's `local()' doesn't have the effect of Lisp's `let'.

It should. At least, there should be an easy way to make a local binding of a Lisp variable in Perl.
Input/Output.

If Perl code tries to read from STDIN, Emacs becomes unresponsive. This is very distressing. Also, Perl loves to print error and warning messages to STDERR, which can be disconcerting. Perl's use of Standard I/O must be controlled. (I shudder to think what would happen if you used Perl compiled with sfio.)
%ENV, %SIG, `setenv'.

Perl and Emacs use environment variables and signal handlers in different, incompatible ways. This needs to be coordinated. I've made a start with %ENV, but more needs to be done.
Probably can't use a coderef as an error handler or protected form.

I think this will be easy to fix, I just haven't had the need.
A crash is likely if Perl code modifies `&Emacs::Lisp::Object::DESTROY' or the scalar value in an `Emacs::Lisp::Object' blessed reference.

These would be somewhat tedious to fix. Don't do these things.

See also the (many) FIXMEs in src/perlmacs.c and elsewhere in the patched Emacs source.

CAVEATS

Circular data structures are bad.

See "Two-Phased Garbage Collection" in perlobj. Lisp data structures may be recursive (contain references to themselves) without the danger of a memory leak, because Lisp uses a periodic-mark-and-sweep garbage collection model. However, if a recursive structure involves any Perl references, it may never be destroyable.

For best results, Perl code should deal mainly with Perl data, and Lisp code should deal mainly with Lisp data.
Cross-language references incur overhead.

For the benefit of Lisp's garbage collection, all Perl data that is referenced by Lisp participates in the mark phase. For the benefit of Perl's garbage collection, all Lisp objects that are referenced by Perl maintain a reference count.

A chain of Perl -> Lisp -> ... -> Perl references may take several garbage collection cycles to be freed. It is therefore probably best to keep the number and complexity of such references to a minimum.

To the extent that the Perl-to-Emacs interface is independent of the Lispish implementation of Emacs, these performance issues may be fixable by reimplementing Emacs' internals, or by rewriting Perl in Lisp.... but don't hold your breath. ;-)
Perl and Lisp don't trap each other's exceptions.

Perl's eval won't trap Lisp errors. Lisp's condition-case won't trap Perl errors, although perl-eval will convert a Perl error into a Lisp error (unlike perl-call).

TODO

Special forms: let, catch, unwind-protect, condition-case, etc.
Better support for Lisp macros.
Parse the cmd line as Perl unless prog name contains "emacs".
Find a way to convert filehandles to the Emacs equivalent.
Complete the plist TIEHASH interface.
Document or scrap the vector TIEARRAY interface.
Improve perl-eval-buffer, perl-load-file, et al. (in C?)

ACKNOWLEDGMENTS

These are among the giants on whose shoulders we stand:

Larry Wall, inventor of Perl.: 'Nuff said.
The developers of GNU, and Richard Stallman in particular.: Many thanks for the most beautiful code base that it has ever been, or will ever likely be, my pleasure to hack.
John McCarthy, inventor of Lisp.
The inventors of C.: Both Perl and Emacs are written in C. This whole thing kind of rests on that fact.
�Évariste Galois (1811-1832) and Wolfgang Amadeus Mozart (1756-1791).: Each of them demonstrated just how much a young man can accomplish with a good mind.
Ludwig van Beethoven (1770-1827).: Showed that even neurotic, deaf, aging crabapples can, from time to time, engender lasting beauty.
Tim Bunce, author of the `DynaLoader' module and much else.: I was lucky enough to come onto the Perl scene soon after dynamic loading had reached its present form (well, but before swig appeared). How you all got by before then completely baffles me.
Doug MacEachern, author of the `ExtUtils::Embed' module.: ExtUtils::Embed is a cornerstone of Perlmacs.

This list is incomplete.

Personal thanks to Nate Patwardhan, who sparked my early interest in Perl--and shared his .emacs with me--during our NFIC days. Nate also introduced me to gdb under gud-mode, O well was I served! :)

Thanks also to Ilya Zakharevich for (1) encouraging me in my first contribution to the Perl development effort (an xsubpp patch), and (2) a comment in cperl-mode.el about changing Emacs C source. If not for that comment, I may never have realized that it is even possible for mortals to change Emacs C source. ;-) Although I didn't implement the change he requested, I hope Ilya approves.

COPYRIGHT

This program is free software; you can redistribute it and/or modify
it under the terms of the GNU General Public License as published by
the Free Software Foundation; either version 2 of the License, or
(at your option) any later version.

This program is distributed in the hope that it will be useful, but
WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
General Public License for more details.

You should have received a copy of the GNU General Public License
along with this program; see the file COPYING.  If not, write to the
Free Software Foundation, Inc., 59 Temple Place, Suite 330, Boston,
MA 02111-1307  USA

Please note: The GNU Emacs license (which is the GNU General Public License or "GPL") requires that all extensions and code designed specifically for use with Emacs be distributable under the same license. At least, that is the intention of its author. This includes dynamically linked code such as the Emacs::Lisp module and (probably) any other Perl modules that use Emacs::Lisp or the GPL-covered functions of Emacs. Refer to the file COPYING and the Emacs documentaion for full details.

	Global
`s`	Focus search bar
`?`	Bring up this help dialog

	GitHub
`g` `p`	Go to pull requests
`g` `i`	go to github issues (only if github is preferred repository)

	POD
`g` `a`	Go to author
`g` `c`	Go to changes
`g` `i`	Go to issues
`g` `d`	Go to dist
`g` `r`	Go to repository/SCM
`g` `s`	Go to source
`g` `b`	Go to file browse

	Search terms
module: (e.g. module:Plugin)
distribution: (e.g. distribution:Dancer auth)
author: (e.g. author:SONGMU Redis)
version: (e.g. version:1.00)

NAME

SYNOPSIS

In Emacs

In Perl

DESCRIPTION

EMACS SUPPORT FOR PERL

Functions

Data Conversions

Scripts

PERL SUPPORT FOR LISP

Functions

Symbols

Variables

Property Lists

Special Forms

BUGS

CAVEATS

TODO

ACKNOWLEDGMENTS

COPYRIGHT

SEE ALSO

Module Install Instructions