NAME

Emacs::Lisp - Low-level support for Perl embedded in GNU Emacs

SYNOPSIS

In Emacs

M-x perl-eval-expression RET 2+2 RET
M-x perl-eval-region RET
M-x perl-eval-buffer RET
... and more ...

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("*test*"));
  &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 modules that give everything in Emacs a nice, object-oriented Perl wrapping.

LISP SUPPORT FOR PERL

The pmacs program can compile and evaluate Perl code via Emacs Lisp, independently of the Emacs::Lisp module.

Functions

Some Perl-related functions are built into Lisp. Use `C-h f <function-name> RET' within Emacs for documentation on these.

perl-eval-expression  EXPRESSION
perl-eval-region      START END
perl-eval-buffer
perl-load-file        NAME
perl-eval             STRING &optional CONTEXT
perl-call             SUB &optional CONTEXT &rest ARGS
perl-eval-and-call    STRING &optional CONTEXT &rest ARGS
make-perl-interpreter &rest ARGV
get-perl-interpreter
set-perl-interpreter  INTERPRETER
perl-run              &optional INTERPRETER
perl-destruct         &optional INTERPRETER

Data Conversions

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

Whatever Perl gives to Lisp should be dereferenced once.

A Perl reference gets converted into a Lisp reference to the thing referenced, not a Lisp reference to the Perl reference. For example, this code
```
setq { $x = 16 };
```
sets the Lisp variable x to the Lisp integer 16, whereas
```
setq { $x = \16 };
```
sets it to an object of type perl-scalar which holds a Perl number 16.
Some Perl types are dereferenced more than once.

Lists are a central data structure in Lisp. To make it as easy as possible to pass lists to Lisp functions that require them, Perl array references become Lisp lists. Therefore, a Perl expression such as
```
["x", ["y", 1]]
```
is converted to
```
'("x" ("y" 1))
```
in Lisp. Likewise, there is a convenient way to construct Lisp vectors. Just add \ to the arrayref to make it an arrayref ref. For example, \[1, 2, undef] becomes [1 2 nil].

This kind of conversion entails quite a bit of overhead and precludes "passing by reference" between the two languages, since it is a "deep" copying operation. Changes made by Lisp to the list will not affect the Perl array of which it is a copy.

All of the above comments apply in reverse when one converts Lisp lists and vectors to Perl.

If you would rather deal in shallow copies, use the "lisp" function and/or the Emacs::Lisp::Object function space, e.g.:
```
$x = lisp [1, 2, 3];
print ref($x);           # "Emacs::Lisp::Object"
print ref($x->to_perl);  # "ARRAY"
print @{&list(2, 3)};    # "23"

$x = Emacs::Lisp::Object::list(2, 3);
print ref($x);           # "Emacs::Lisp::Object"
print @{$x->to_perl};    # "23"
```
But see "CAVEATS" about storing references to Lisp objects.
Similar types are converted to each other.

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 package main 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 unchanged (but often copied).

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

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

Scripts

Perlmacs can run Perl programs. By default, Perlmacs is installed under two names, pmacs and perlmacs. Which name is used to invoke the program can determine how it parses its command line.

If perlmacs is used (or, more precisely, any name containing "perl"), it behaves like Perl. (See perlrun for the list of invocation options.) Otherwise, it behaves like Emacs (opening a window, creating a buffer, etc.). In either case, the first command line argument can override the name. If it is --emacs, Emacs takes control. If it is --perl, the program runs in Perl mode.

The Emacs module (that is, the Perl module named `Emacs') includes support for starting an Emacs editing session from within a Perlmacs script. See Emacs. NOTE: As of this writing, the Emacs module has not been released. Check CPAN.

PERL SUPPORT FOR LISP

The Emacs::Lisp module allows Perl programs to invoke Lisp functions and handle Lisp variables 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 really only needed for calling Lisp functions, such as read, eval, and print, which are Perl keywords. But using it is a good habit.

If you don't like the ampersand or don't want an AUTOLOAD sub exported to your namespace, I suggest you either put parentheses after "use Emacs::Lisp" or import to a different package, and use qualified function names. For example:

use Emacs::Lisp ();
Emacs::Lisp::insert("hello\n");

{package L; use Emacs::Lisp;}
L::insert("goodbye\n");

Symbols

Many Lisp functions take arguments that may be, or are required to be, symbols. In Lisp, a symbol is a kind of name, but does not have the same type as a string.

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)

The above is actually an abbreviated syntax for this:

(run-at-time nil 1 (quote 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 example.)

Only globs from package main may be used as Lisp symbols, so code that is compiled in another package must use the form \*::sym rather than \*sym.

When comparing the returned values of Lisp functions to each other and to symbols, it is best to use the Lisp eq function instead of Perl's equality operators.

### PREFERRED
if (&eq(&type_of($x), \*::cons)) { ... }

### PROBABLY OK
if (&type_of($x) eq \*cons) { ... }
if (&type_of($x) == \*cons) { ... }

Variables

In Lisp, variables play a role akin to that of Perl scalar variables. 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 Perl when $varname is used in 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)

(but you would probably rather use let instead, for which there is still no convenient Emacs::Lisp equivalent). See also the setq function below.

Property Lists

Lisp symbols all have an associated object called a plist, for "property list". The plist is an object just like any other, but it is typically used in a way vaguely resembling Perl's hashes.

Plists are not used nearly as often as Lisp functions and variables. If you are new to Lisp, you can probably skip this section.

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. 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 elements of %any_name will get or set the corresponding 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} = [\*booboo, \*error];
$can_upcase = ! $upcase_region{\*disabled};

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

Macros

Lisp macros, such as setq and defun, do not work the same way functions do, although they are invoked using the function syntax. (Here you see the vast philosophical chasm separating Perl from Lisp. While Perl might have five syntaxes to mean the same thing, Lisp has one syntax with two meanings!)

Some macros are equivalent to Perl operators, such as if and while. Others have meanings peculiar to Lisp. A few macros are implemented in Emacs::Lisp. They are described below. If you try to call a macro that has not been implemented, you will get an error message which may propose an alternative.

catch SYMBOL,CODE

Evaluate CODE in a Lisp catch construct. At any point during CODE's execution, the throw function may be used to return control to the end of the catch block. For example:

$x = catch \*::out, sub {
    $y = 1;
    &throw(\*::out, 16);
    $y = 2;
};
print $x;  # prints 16
print $y;  # prints 1

Some Perl constructs have similar functionality to throw, for example, "return" and "last LABEL". However, they do not work with catches in Lisp code.

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 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.

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's defun uses a SPEC returned by the "interactive" function to specify a command's interactivity. If no SPEC is given, the function will still be callable by Lisp, but it will not be available to the user via "M-x <function-name> RET" and cannot be bound to a sequence of keystrokes. 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 reverse-region-words RET).

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);
       });

If you tried this example and invoked the help system, you may have noticed something not quite right in the message. It reads as follows:

reverse-region-words is an interactive Lisp function.
(reverse-region-words &optional START END &rest ARGS)

Reverse the order of the words in the region.

Notice the part about "&optional" and "&rest". This means that Lisp thinks the function accepts any number of arguments. It knows the names of the first two because of the assignment "my ($start, $end) = @_".

But our function only works if it receives two args. Specifying a prototype fixes this:

sub ($$) {
    my ($start, $end) = @_;
    ...
}

reverse-region-words is an interactive Lisp function.
(reverse-region-words START END)

interactive SPEC

interactive

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

What distinguishes a "command" from an ordinary function, in the Emacs parlance, is the presence of an interactive specifier in the defun expression.

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 of either of these forms:

$var = EXPR;
$hash{$key} = EXPR;

Every such $var and %hash 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 this:

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 variables, 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

These are some of the known bugs in Perlmacs and Emacs::Lisp. See also the file BUGS in the Perlmacs distribution. If you find other bugs, please check that you have the latest version, and email me.

Within Lisp code, everything defaults to package `main'.

It would perhaps be best to give the Lisp evaluation environment the notion of a "current package" such as Perl has.
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.
A crash is likely if Perl code modifies the scalar value in an `Emacs::Lisp::Object' blessed reference or explicity calls DESTROY on it.

Don't do that.
Possible memory leaks.

I have not tested for memory leaks.

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 collector.

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 a slight 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 (kind of) reference count.

A chain of Perl -> Lisp -> ... -> Perl references may take several garbage collection cycles to be freed. (At least, that is my theory. I haven't verified it experimentally.) 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 are fixable in principle by reimplementing Emacs' internals.)

TO DO

Bundle Perlmacs and its related modules.
Provide XSubs for common, non-evalling functions.

There is substantial overhead in calling an arbitrary Lisp function, because care must be taken to restore the Perl interpreter's state when Lisp performs a non-local jump out of the function call. This can be avoided in the case of functions like cons, null, bufferp, car, eq, symbol-value, etc., for which a simple check can determine whether a jump will occur.
Special forms: unwind-protect, let, defmacro, defvar.
Find a way to convert between filehandles and the Emacs equivalent.
Make a way to get a tied filehandle that reads a buffer.
Improve perl-eval-buffer, perl-load-file, et al.

ACKNOWLEDGMENTS

These are among the giants on whose shoulders we stand:

Larry Wall, inventor of Perl and Patch.: '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.
Dennis Ritchie, inventor of C.: Both Perl and Emacs are written in C. The existence of Perlmacs 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. How you all got by before then completely baffles me.
Doug MacEachern, author of the `ExtUtils::Embed' module and mod_perl.: ExtUtils::Embed is a cornerstone of Perlmacs.
Eric Raymond, author of gud-mode.: Perlmacs is largely a product of GDB and gud-mode.

This list is incomplete.

Thank you, Di Zhao <dzhao@primeon.com>, for braving the alphas and showing me what can be done with Perlmacs. If not for you, I would still be wondering whether it could possibly have any use.

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.

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. According to Richard Stallman, 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

LISP SUPPORT FOR PERL

Functions

Data Conversions

Scripts

PERL SUPPORT FOR LISP

Functions

Symbols

Variables

Property Lists

Macros

BUGS

CAVEATS

TO DO

ACKNOWLEDGMENTS

COPYRIGHT

SEE ALSO

Module Install Instructions