Emacs-EPL

 view release on metacpan or  search on metacpan

doc/epl.info  view on Meta::CPAN

EPL
***

   This is edition 0.2 of the EPL Reference Manual, corresponding to
EPL version 0.7.

   EPL (Emacs Perl) is a library of Lisp functions and Perl modules that
let you write Emacs extensions in Perl.

* Menu:

* Preface::                     Why I'm here.
* Introduction::                Beginning with an example.
* Features::                    How Perl looks to Lisp, how Lisp looks to Perl.
* Configuration::               Changing the defaults.
* Internals::                   What happens under the hood.

Appendices

* Copying Conditions::          The GNU Free Documentation License.

doc/epl.info  view on Meta::CPAN

(http://www.gnu.org/software/emacs/) and XEmacs (http://www.xemacs.org)
that lets you write commands in Perl.  It is also a programming
interface for Elisp (*note Emacs Lisp::) programs to use Perl features
and an interface for Perl to use Emacs.

   This document assumes knowledge of Emacs terms such as "the
minibuffer" and "`M-x'" (*note Running Commands by Name: (emacs)Top.).
It assumes knowledge of Perl references and nested data structures
(perlref(1)), and packages and modules (perlmod(1)).

* Menu:

* Perl Example::                An example: Find files containing regex.
* History::                     EPL uses IPC, not translation or embedding.
* Emacs Lisp::                  You need the Emacs Lisp Reference Manual.
* Coding Conventions::          Why the Perl examples use `&FUNCTION()'.


File: epl.info,  Node: Perl Example,  Next: History,  Up: Introduction

Perl Example

doc/epl.info  view on Meta::CPAN

Features
********

   This chapter describes EPL's mapping between Perl's language features
and Emacs Lisp's.  Perl and Lisp are quite different, so some features
favored by one language are imperfectly or awkwardly reproduced in the
other.  EPL follows Perl's philosophy of making simple things easy and
hard things possible.

* Menu:

* Data Conversion::             Working with each other's data types.
* Functions::                   Calling each other's functions, `defun'.
* Control Structures::          Exceptions; `throw', `signal', `die'.
* Input/Output::                Perl's primitives are redefined in Emacs.
* Caveats::                     It's not always a happy marriage.


File: epl.info,  Node: Data Conversion,  Next: Functions,  Up: Features

doc/epl.info  view on Meta::CPAN

allows the recipient to examine a structure using its built-in
accessors, but changes will not apply to the original.  Also, language
peculiarities result in information loss during some conversions, so
pass-by-value is not completely reversible (*note Conversion Is
Imperfect::).

   This section describes the conversions that apply to each language's
scalar and container types.  For a complete description of Lisp types,
see *Note Lisp Data Types: (elisp)Lisp Data Types.

* Menu:

* Scalars::                     Lisp has three scalar types.
* The Null Value::              `undef' and `()' are `nil'.
* Symbols and Globrefs::        `\*::sym' is `'sym'.
* Lists and Arrayrefs::         `["fnord"]' is `'("fnord")'.
* Vectors::                     `\[42]' is `[42]'.
* Conses::                      The `Emacs::Lisp::Cons' type.
* Scalar References::           The `perl-ref' type.
* Code References::             `\&frob' is a lambda expression.
* Hash Tables::                 Not yet implemented.

doc/epl.info  view on Meta::CPAN

Emacs Types
-----------


File: epl.info,  Node: Functions,  Next: Control Structures,  Prev: Data Conversion,  Up: Features

Functions
=========

* Menu:

* Evaluation::                  `perl-eval'.
* Ordinary Functions::          `perl-call', `use Emacs::Lisp;'.
* Pass-by-Reference::           How to inhibit data conversion.
* Commands::                    Extending Emacs without Lisp, `defun'.


File: epl.info,  Node: Evaluation,  Next: Ordinary Functions,  Up: Functions

Evaluation

doc/epl.info  view on Meta::CPAN

Input/Output
============


File: epl.info,  Node: Caveats,  Prev: Input/Output,  Up: Features

Caveats
=======

* Menu:

* References Incur Overhead::   Memory management hurdles.
* Conversion Is Imperfect::     Natural mappings are not always 1-to-1.


File: epl.info,  Node: References Incur Overhead,  Next: Conversion Is Imperfect,  Up: Caveats

References Incur Overhead
-------------------------

doc/epl.info  view on Meta::CPAN

Conversion Is Imperfect
-----------------------


File: epl.info,  Node: Configuration,  Next: Internals,  Prev: Features,  Up: Top

Configuration
*************

* Menu:

* Installation::                Lisp files, Perl modules, documentation.
* The Easy Way::                We like the defaults.
* Starting a Perl Process in Emacs::   `make-perl-interpreter'.
* Starting an Emacs Process in Perl::  `use Emacs::Lisp;'.


File: epl.info,  Node: Installation,  Next: The Easy Way,  Up: Configuration

Installation

doc/epl.info  view on Meta::CPAN

   This chapter introduces the concepts involved in supporting
single-threaded distributed exception handling and garbage collection
for languages like Perl and Emacs Lisp.  These languages have a lot
more in common underneath than meets the eye.

   The chapter ends with a more concrete description of EPL's protocol.
This information changes with great frequency and may be completely
outdated by the time you read this.

* Menu:

* Debugging Options::           Dumping traffic to stderr or a buffer.
* Transport Layer::             Media of interprocess communication.
* Message Types::               What interpreters can say to each other.
* State Transitions::           The message stream grammar.
* Protocol::                    Current EPL protocol (*subject to change*).


File: epl.info,  Node: Debugging Options,  Next: Transport Layer,  Up: Internals

doc/epl.info  view on Meta::CPAN

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

   You may distribute copies of this documentation in accordance with
the *Note GNU Free Documentation License::, Version 1.1 or any later
version published by the Free Software Foundation; with no required
Invariant Sections, Front-Cover texts, or Back-Cover Texts.

* Menu:

* GNU Free Documentation License::    The GNU FDL.


File: epl.info,  Node: GNU Free Documentation License,  Up: Copying Conditions

GNU Free Documentation License
==============================

                        Version 1.1, March 2000

doc/epl.info  view on Meta::CPAN

recommend releasing these examples in parallel under your choice of
free software license, such as the GNU General Public License, to
permit their use in free software.


File: epl.info,  Node: Index,  Prev: Copying Conditions,  Up: Top

Index
*****

* Menu:

* $Emacs::EPL::debugging:                Debugging Options.
* connection types:                      Transport Layer.
* debugging EPL:                         Debugging Options.
* dumping message traffic:               Debugging Options.
* Emacs::EPL::debug:                     Debugging Options.
* epl-debug:                             Debugging Options.
* epl-debugging:                         Debugging Options.
* FDL, GNU Free Documentation License:   GNU Free Documentation License.
* Internals:                             Internals.